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Preface 


Intended Audience 

This manual is intended for experienced programmers who know at least 
one computer language. Some features of VAXTPU, for example, the 
callable interface and the built-in procedure FILE_PARSE, are intended 
for system programmers who have a good understanding of VMS system 
concepts. Relevant documents about the VMS operating system are listed 
under Associated Documents. 


Document Structure 


This manual consists of six expository chapters, a reference section, and 
seven appendixes. The six chapters discuss the following topics: 

• Chapter 1 contains an overview of VAXTPU. 

• Chapter 2 provides detailed information on VAXTPU data types. 

• Chapter 3 discusses the lexical elements of VAXTPU. These include 
the character set, identifiers, variables, constants, and reserved words, 
such as VAXTPU language statements. 

• Chapter 4 describes VAXTPU program development. 

• Chapter 5 describes how to invoke VAXTPU. 


• Chapter 6 discusses the VAXTPU screen manager and screen 
management issues. 

The VAXTPU Reference Section (Chapter 7) provides detailed descriptions 
of the VAXTPU built-in procedures. 


The seven appendixes are organized as follows: 

• Appendix A contains sample procedures written in VAXTPU. 















Appendix B contains sample procedures written in DECwindows 
VAXTPU. 

Appendix C describes terminals supported by VAXTPU. 

Appendix D lists each VAXTPU message, its abbreviation, and its 
severity level. 

Appendix E contains the DEC Multinational Character Set. 

Appendix F lists the file types that VAXTPU supports. 

Appendix G discusses EVE$BUILD, a tool that enables you to layer 
applications onto EVE or build new VAXTPU applications. 
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Associated Documents 


To leam how to use the Extensible VAX Editor (EVE), see the Guide to 
VMS Text Processing. For reference information on EVE commands, see 
VMS EVE Reference Manual. 

The VMS Utility Routines Manual contains a chapter presenting the 
VAXTPU callable interface. 

The VMS System Messages and Recovery Procedures Reference Manual 
contains the VAXTPU messages, as well as an explanation and suggested 
user action for each message. The messages are listed alphabetically by 
the abbreviation for the message text. 

The Overview of VMS Documentation briefly describes all VMS system 
documentation, defining the intended audience for each manual and 
providing a synopsis of each manual’s contents. 

The VMS DCL Dictionary describes the VMS DCL commands that help 
you create, copy, and print files containing VAXTPU programs. 

The VMS System Services Volume describes system services. 

The Introduction to VMS System Routines and VMS Utility Routines 
Manual describe utility routines. 

The VMS Run-Time Library Routines Volume describes routines of the 
run-time library. 

The VMS Record Management Services Manual describes VMS RMS 
services. 


Conventions 


The following conventions are used in this document: 


I Return | 


mouse 


MB1, MB2, MB3 


The term mouse is used to refer to any pointing 
device, such as a mouse, a puck, or a stylus. 

MB1 indicates the left mouse button, MB2 Indicates 
the middle mouse button, and MB3 indicates the right 
mouse button. (The buttons can be redefined by the 
user.) 

In examples, a key name (usually abbreviated) shown 
within a box indicates that you press a key on the 
keyboard; in text, a key name is not enclosed in a 
box. In this example, the key is the Return key. (Note 
that the Return key is not usually shown In syntax 
statements or in all examples; however, assume 
that you must press the Return key after entering a 
command or responding to a prompt.) 
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CTRUC 

red ink 


{} 

n 

I,... I 

[] 

quotation marks 
apostrophes 

UPPERCASE letters 
and special symbols 


A key combination, shown in uppercase with a slash 
separating two key names, indicates that you hold 
down the first key while you press the second key. 

For example, the key combination CTRL/C indicates 
that you hold down the key labeled CTRL while 
you press the key labeled C. In examples, a key 
combination is enclosed In a box. 

Red ink indicates information that you must enter from 
the keyboard or a screen object that you must choose 
or click on. For online versions, user Input is shown in 

bold. 

In examples, a vertical series of periods, or ellipsis, 
means either that not all the data that the system 
would display in response to a command Is shown or 
that not all the data a user would enter is shown. 

Braces enclose a mandatory portion of the format of 
a built-in procedure or lexical element. When braces 
enclose a stacked list of items, you must choose one 

of the items. For example: | | 

Double brackets in examples show an optional portion 
of the format of a built-in procedure or lexical element. 
When double brackets enclose an item or series of 
items, you can select one of the items. For example: 



Double brackets enclosing a comma and horizontal 
ellipsis mean that you can repeat the preceding item 
one or more times, separating two or more Items with 
commas. For example: 

parameter [[,...]] 

Delimits a case label. Single brackets do not indicate 
optional parameters In this manual. 

The term quotation marks is used to refer to double 
quotation marks ("). The term apostrophe (’) is used 
to refer to a single quotation mark. 

Uppercase letters and special symbols In syntax 
descriptions and sample procedures indicate VAXTPU 
reserved words and predeclared identifiers, and other 
user Input that must be typed exactly as shown. For 
example: 

PROCEDURE 

UNDERLINE 

String constants are shown in lowercase to emphasize 
that they are strings. However, they, too, must be 
typed exactly as shown. 
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lowercase letters 


user 


filespec 



Lowercase letters in syntax descriptions and sample 
procedures represent elements that you must replace 
according to the description in the text. For example, 
when a data type, such as buffer, is used in a syntax 
example, replace it with the variable name assigned 
to the data Item when it was created. In the following 
assignment statement, my__buffer_variable is the 
variable name assigned to the buffer you are creating: 

my_buffer_variable := 

CREATE_BUFFER (' my_buf_name', ' niy_f ile_name') 

To specify a buffer as a parameter for a VAXTPU 
built-in procedure, use the variable for the buffer. For 
example, to erase the contents of the buffer created 
in the preceding statement, enter the following: 

ERASE (my_buffer__variable) 

Many of the sample procedures in this manual have 
the prefix user_ as a part of the procedure name. 
Digital suggests that you replace the prefix user with 
your Initials. This or some other convention helps 
to ensure that the variables and procedure names 
that you create do not conflict with either VAXTPU 
built-in procedure names, or the procedure names 
and variables of your editing interface. 

Mnemonic for file specification. 
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VAXTPU Reference Section 

This section contains detaiied descriptions of the buiit-in procedures provided 
by the VAX Text Processing Utiiity. 










VAXTPU Built-In Procedures 


This chapter describes each of the VAXTPU built-in procedures. The 
chapter is divided into two sections. 

In Section 7.1, the built-in procedures are grouped according to the 
functions that they perform so you can see at a glance which built-in 
is related to what task. In Section 7.2, the built-in procedures are listed 
alphabetically. Each built-in is described in detail. 

Some built-in procedures do not return useful values. The descriptions of 
these built-ins do not show a return value in the format section. However, 
these built-ins return 0 when used on the right-hand side of an assignment 
statement. 

Some entries in this chapter describe language elements or ke 5 rwords that 
are not built-in procedures. These elements and keywords are included in 
this chapter because they are used in the same way built-ins are used. 


Built-In Procedures Grouped According to Function 


When you want to perform editing tasks, use the following lists to help 
you identify which built-in procedures are related to a particular task. For 
more information about a built-in procedure, see its in^vidual description 
in Section 7.2. 


.1 Screen Layout 


ADJUST_WINDOW (window, integerl, integer2) 




REFRESH 

SET (DISPLAY_VALUE,window,display_value_integer) 
SET (HEIGHT, SCREEN, length) 



, NONE 
,BOLD 


• SET (PROMPT_AREA, integerl, integer2 < , BLINK >) 


,REVERSE 
. , UNDERLINE , 
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VAXTPU Built-In Procedures 

7.1 Built-In Procedures Grouped According to Function 


SET (SCREEN.UPDATE 


SET (SCROLLING, window 
integers) 


SET (STATUS_LINE, window < 




integerl, integer2, 


, NONE 
.BOLD 
, BLINK 
,REVERSE 

, SPECIAL.GRAPHICS 
, UNDERLINE 


, string) 

• SET (TEXT, < 


' widget, string 

( BLANK.TABS 
window, I GRAPHIC.TABS 
I NO TRANSLATE 


11 ’ 


• SET (VIDEO, window < 


.NONE 
.BOLD 

, BLINK ^) 

,REVERSE 
, UNDERLINE J 


window 

• SET (WIDTH, { ALL 

SCREEN 
SHIFT (window, integerl) 


{ window ) 

ALL /, width_int) 
SCREEN J 


UNMAP ( ( }) 

I window ) 

UPDATE( { 


ALL 

window 


)> 


7.1.2 


Cursor Movement 

• CURSOR_HORIZONTAL (integerl) 

• CURSOR_VERTICAL (integerl) 


SCROLL (window I .integerl I) 

SET (COLUMN_MOVE_VERTICAL 


SET (CROSS_WINDOW_BOUNDS 


r,ON 1 
\ , OFF 

f,ON 1 
\ , OFF }’ 


SET (DETACHED_ACTION, SCREEN 
buffer 
learn 

I, program J) 
range 
string 


7-2 

















VAXTPU Built-In Procedures 

7.1 Built-In Procedures Grouped According to Function 


7.1.3 Moving the Editing Position 


MOVE_HORIZONTAL (integer) 
MOVE_VERTICAL (integer) 
buffer 

BUFFER_BEGIN 
BUFFER.END 
integer 
LINE.BEGIN 
LINE.END 
marker 
MOUSE 


POSITION ( < 


range 

window 




7.1.4 Text Manipulation 


• APPEND LINE 


BEGINNING_OF ( 


buffer 

range 


) 


buffer 1 ( 

CHANGE_CASE ( { range I 

, IN.PLACE 
, NOT_IN_PLACE 


string 

) 


INVERT 

LOWER 

UPPER 


buffer 

COPY_TEXT ( { rangel ^) 
string 

CREATE_BUFFER (stringl |[,string2 l[,bufferl]l I[,string3]l I) 

markerl 


CREATE.RANGE ( 


}■ 


r markerl 

\ delimiting_keyword 

f marker2 1 

\ delimiting_keyword j 
I, attribute_keyword 3) 

buffer 1 

EDIT ( { range >, keywordl|[,...3 l[,ke3rword21 [[ ,ke3rword33) 
string J 

r buffer lx 
\ range J 

buffer 
range 

ERASE.CHARACTER (integer) 

ERASE LINE 


) 
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7.1 Built-In Procedures Grouped According to Function 


• FILE_PARSE (filespec |[ .stringl I[,string2 

I, NODEl I, DEVICE]] I, DIRECTORY]] I, NAME]] 
I, TYPEI I, VERSION]] 31) 


• FILE_SEARCH (filespec I, stringl I, string2 

t NODE! I, DEVICE! I, DIRECTORY! I, NAME! 

I, TYPE! I, VERSION! !!) 

• FILL ( I I i[ string I, integerl ][, integer2 ][, integers !3 !!) 

1^ range J 




MARK( 


BUNK 

BOLD 

NONE 

FREE.CURSOR 

REVERSE 

UNDERLINE 




• MESSAGE.TEXT ( | | I, integer2 I ,FAO-parameter3 !) 






MODIFY RANGE (range, ( , , 1, 

“ I aelinutmg_ke 3 rword J 

{ marker2 1 

delimiting_ke 5 rword J 

][, attribute_ke 5 rword !) 

( buffer ] 

MOVE_TEXT( i rangel J) 

[ string J 

READ_FILE (stringl) 


SEARCH ( 


I 


ANCHOR 

LINE.BEGIN 

LINE_END 

PAGE.BREAK 

pattern 

REMAIN 

string 

UNANCHOR 
f ,EXACT 
I ,NO_EXACT 
[ ,integer 


/,FORWARD \ 
\ , REVERSE J 



SEARCH.QUIETLY ( < 


ANCHOR 

LINE.BEGIN 

LINE.END 

PAGE_BREAK 

pattern 

REMAIN 


/,FORWARD \ 
\ , REVERSE J 


string 

I UNANCHOR 
( ,EXACT 
I I , NO_EXACT 
[ ,integer 


( , buffer 
\ ,rangel 


} 


!!) 
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7.1 Built-In Procedures Grouped According to Function 


7.1.5 


BLINK 
BOLD 

SELECT ( ^ NONE 

REVERSE 
I UNDERLINE I 
SELECT_RANGE 

SET (ERASE.UNMODIFIABLE, buffer, { }) 

SET (MODIFIABLE, buffer | ’ |) 

SET (MODIFIED, buffer, { }) 

SPLIT_LINE 

( buffer 

TRANSLATE ( ^ range string2, strings 
string 

.PLACE 

PLACE 


|[ / IN_PLACE \ H 

[[ ’ \ NOT_IN_PLACE J J| 


• WRITE_FILE ( I stringl) 

\ range J’ 


Pattern Matching 


• ANCHOR 

( buffer ^ 

• ANY ( < range >, integerl) 

[ string J 

• ARB (integer) 

• LINE_BEGIN 

• LINE.END 

( buffer I 

• MATCH( grange J) 

[ string J 

( buffer \ 

• NOTANY ( < range >, integerl) 

[ string J 

• PAGE.BREAK 

• REMAIN 

buffer I 

. SCAN<{ra^^ ) «-{ }» 
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7.1 Built-In Procedures Grouped According to Function 


7.1.6 


. ar^AXTT / / I IT / FORWARD \ r.. 

SCANL ( < range > I, | ugyjjjjsE | 

string J 

. QIDATVT / / 1 IT / FORWARD \ T,s 

SPAN ( ^ range > E, | | 

[ string J 

. QUAIVTT ^ I I (T / FORWARD \ -n. 

SPANL ( < range > I, | REVERSE 1 ^ 

string j 


• UNANCHOR 


Status of the Editing Context 

• CURRENT_BUFFER 

• CURRENT.CHARACTER 

• CURRENT.COLUMN 

• CURRENT.DIRECTION 

• CURRENT.LINE 

• CURRENT.OFFSET 

• CURRENT.ROW 

• CURRENT_WINDOW 

• DEBUG.LINE 

• ERROR 

• ERROR.LINE 

• ERROR.TEXT 

• GET_INFO (parameterl, paraineter2 E, ... I) 

• RECOVER_BUFFER (old_buffer_naine 

• LOCATE_MOUSE (window, x_integer, y_integer) 

• SET (AUTO_REPEAT | ’ |) 

• }) 

• SET (DEFAULT.DIRECTORY, new_default_string) 


, joumal_file_name 
, template_buffer 


• SET (DEBUG 


, ON 


, OFF 

,PROGRAM 


, ALL 
, buffer 
, program 
, range 
, string 


• SET (FACILITY.NAME, string) 


E ,value I) 
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7.1 Built-In Procedures Grouped According to Function 


• SET (FORWARD, buffer) 

• SET (INFORMATIONAL ( ’ 1) 

\ ,OFF J 

• SET (INSERT, buffer) 

• SET (JOURNALING, buffer | Qpp | I,file_name_string I) 
or 


SET (JOURNALING, integer) 

SET (KEYSTROKE RECOVERY | \) 

\ OFF / 

SET (LEFT_MARGIN, buffer, integer) 

f , buffer2 

SET (LEFT_MARGIN_ACTION, bufferl 


, leam_sequence 
, program 
, range 
, string 


SET (LINE_NUMBER | ’ |) 

SET (MARGINS, buffer, integerl, integer2) 

SET (MAX_LINES, buffer, integer) 

SET (MESSAGE_ACTION_LEVEL, | |) 

NONE 

SET (MESSAGE_ACTION_TYPE, { BELL 


r NONE ) 

S, { BELL J) 
I REVERSE J 


SET (MESSAGE.FLAGS, integer) 
SET (MOUSE, }) 

SET (NO.WRITE, buffer | ’ 

SET (OUTPUT_FILE, buffer, string) 
SET (OVERSTRIKE, buffer) 

SET (PAD_OVERSTRUCK_TABS 


) 


SET (RECORD.ATTRIBUTE 

>^_setting_integer 
_setting_integer 


■( 


r,0N 1 

\ , OFF / 

)■{ 


mark 

range 

buffer 


DISPLAY.VALUE 
LEFT MARGIN 


}• 


r display_setting_integer 1, 

\ margin_setting_integer 

or 

[ marker, T] 

range, MODIFIABLE, f }> 
buffer, J ^ ^ 
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7.1 Built-In Procedures Grouped According to Function 


• SET (PERMANENT, buffer) 

SET (REVERSE, buffer) 

SET (RIGHT_MARGIN, buffer, integer) 

SET (RIGHT_MARGIN_ACTION, bufferl 


f , buffer2 
, leam_sequence 
, program 
, range 
L , string 


SET (SPECIAL_ERROR_SYMBOL, string) 
SET (SUCCESS I ’ Qpp |) 

SET (SYSTEM, buffer) 

SET (TAB_STOPS, buffer | ’ 

SET (TIMER I ’ Qpp I II, string])) 

SET (TRACEBACK | ’ |) 

f BUFFERIS] 
KEY_MAP_LISTI[S]1 
KEY_MAPI[S]1 
KEYWORDS 
PROCEDURES 
SCREEN 
SUMMARY 
VARIABLES 
WINDOWIS]) 
buffer 
string 
. window 


SHOW ( - 




Defining Keys 


• ADD_KEY_MAP (key-map-list-name | ’ 

key-map-name |[,...]|) 

• CREATE_KEY_MAP (stringl) 

• CREATE_KEY_MAP_LIST (stringl, string2 I, ... I) 

' buffer 

leam_sequence 

• DEFINE_KEY ( - program 

range 
. stringl 

|[,string3]|]]) 


, key-name I, string2 
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7.1 Built-In Procedures Grouped According to Function 


{ integer 
key-name 
string 

, SHIFT_KEY 
, SHIFT_MODIFIED 
I ^ , ALT_MODIFIED 
, CTRL.MODIFIED 
, HELP.MODIFIED 
, FUNCTION 
, KEYPAD 

LAST.KEY 


I, ...I 3 


) 


LOOKUP.KEY (key-name 


( , COMMENT 'I 
\ ,KEY_MAP \ 
[ , PROGRAM J 


, stringl 
, string2 


) 


REMOVE_KEY_MAP (stringl, string2 I, ALL3) 
SET (KEY_MAP_LIST, string E, buffer, window!) 

r , buffer 


SET (POST_KEY_PROCEDURE, stringl 


SET (PRE_KEY_PROCEDURE, stringl 


, leam_sequence 
, program 
, range 
L string2 

]■ , buffer 
, leam_sequence 
, program 
, range 
i, string2 




SET (SELFJNSERT, string, 

SET (SHIFT.KEY, keyword I ,string 3) 

r , buffer 


SET (UNDEFINED_KEY, stringl 


, leam_sequence 
, program 
, range 
L, string2 


UNDEFINE_KEY (keyword 


, key-map-list-name 
, key-map-name 


) 


7.1.8 Multiple Processing 

• attach K I 

• CREATE.PROCESS (buffer I, string!) 
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buffer 

• SEND ( ^ range ^, process) 
string 


SEND_EOF (process) 

, ON 


SPAWN I (string 


,OFF 


)1 


7.1.9 Program Execution 


ABORT 

BREAK 

COMPILE ( 


buffer 

range 

string 


0 


EXECUTE( 


RETURN 


buffer 

key-name 


, key-map-list-name 
, key-map-name 


leam_sequence 

program 

range 

string 


)) 


SAVE (stringl I[,"NO_DEBUG_NAMES" J 

|[,"NO_PROCEDURE_NAMESl 
I,"IDENT", string2]l) 


7.1.10 DECwindows VAXTPU-Specif ic 


^ [[, closure 


• CREATE.WIDGET (widget_class, widget_name, { screEN^^^^^^ } 

{ buffer 

leam_sequence 
program 
range 
string 

E, widget^args... Ill) 

• CREATE_WIDGET (resource_manager_name, hierarchyjd, 
r parent_widget 1 
I SCREEN / 

^ buffer 

leam_sequence 
E, program 
range 
. string 

E, closure 

E, widget^args... Ill) 
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VAXTPU Built-In Procedures 

7.1 Built-in Procedures Grouped According to Function 


• DEFINE_WIDGET_CLASS (class_name 
I, creation_routine_name 

H , creation_routine_image_name 11) 

DELETE (widget) 

GET.CLIPBOAED 
GET_DEFAULT (stringl, string2) 

f PRIMARY 

GET_GLOBAL_SELECT ( ^ SECONDARY 

I selection_name 

selection_property_name) 

MANAGE_WIDGET (widget I, widget... 1) 


READ.CLIPBOARD 


( PRIMARY 

READ_GLOBAL_SELECT ( ^ SECONDARY 

I selection_name 

selection_property_name) 


REALIZE.WIDGET (widget) 


SEND.CLIENT_MESSAGE({gJ^-|^ECTION 

SET (ACTIVE_AREA, window, column, row [[, width, height I) 


SET (CLIENT_MESSAGE,SCREEN, < 


buffer 

leam_sequence 

program 

range 

string 




SET (DRM_HIERARCHY, filespec E, filespec... J) 

SET (ENABLE.RESIZE, { |) 

I OFF J 


'■{ 


PRIMARY 


SET (GLOBAL_SELECT, SCREEN, { SECONDARY 

selection_name 

SET (GLOBAL_SELECT_GRAB, SCREEN 
( buffer 
leam_sequence 
program 




range 

string 

NONE 


1 ) 


SET (GLOBAL_SELECT_READ, | 

'' buffer2 
learn_sequence 
program 
range 
string 
( NONE 


bufferl 

SCREEN 


I. < 


> 1 ) 
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7.1 Built-In Procedures Grouped According to Function 


SET (GLOBAL_SELECT_TIME, SCREEN, | ^ring’" 

SET (GLOBAL_SELECT_UNGRAB, SCREEN 
' buffer 

leam_sequence 
program y 

range 
string 
NONE 

SET (ICON.NAME, string) 

SET (ICON_PIXMAP,integer,icon_pixmap l[,widget]|) 


I. 


or 


SET (ICON_PIXMAP,bitmap_file_name [[,widget]]) 

SET (ICONIFY_PIXMAP,integer,icon_pixmap |[,widget3) 


or 


SET (ICONIFY_PIXMAP,bitmap_file_name |[,widgetl) 


SET (INPUT_FOCUS 


,SCREEN 
, widget 


) 


SET (INPUT_FOCUS_GRAB, SCREEN I, < 


buffer 

leam_sequence 

program 

range 

string 

NONE 


n) 


SET (INPUT_FOCUS_UNGRAB, SCREEN I, 


buffer 

leam_sequence 

program 

range 

string 

NONE 


SET (MAPPED_WHEN_MANAGED,widget, | }) 

{ widget ) 
array [) 
NONE J 


widget 

SET (MENU_POSITION, mouse_down_button, array 

NONE 


SET (RESIZE.ACTION 


SET (SCREEN.LIMITS, array) 



' buffer 

*T 


leam_sequence 

program 

► 

7 

range 



string 

NONE J 
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7.1 Built-In Procedures Grouped According to Function 


7.1.11 


. SET (SCROLLJAE, window, }, 

• SET (SCROLL_BAR_AUTO THUMB, window, ( HORIZONTAL 

I VERTICAL 



• SET (WIDGET, widget, 

{ widget_args I, widget_args... I }) 

• SET (WIDGET_CALL__DATA, widget, reason_code, request_string, 
keyword I, request_string, keyword...!) 


SET (WIDGET.CALLBACK, widget, 
buffer, 

leam_sequence, 
program, closure) 

range, 
string, 

UNMANAGE_WIDGET (widget I, widget... 1) 

buffer 

WRITE_CLIPBOARD (clipboardjabel, ^ range ^) 


^ array 
buffer 


WRITE_GLOBAL^SELECT ( 


range 

string 

integer 

NONE 


string 


}) 


Miscellaneous 


{ integerl '> 
kejword >) 
stringl J 

• CALL_USER (integer, stringl) 

r DECW_ROOT_WINDOW 
• CONVERT (< SCREEN 
v window 

from_x_integer, from_y_integer, 

DECW_ROOT_WINDOW 
SCREEN 
window 

to_x_integer, to_y_integer) 
CREATE_ARRAY I (integerl I, integer2 J) I 


H 

)■( 


CHARACTERS, 

COORDINATES, 


CHARACTERS 

COORDINATES 


s. } 
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7.1 Built-In Procedures Grouped According to Function 


DELETE(^ 


array 

buffer 

integer 

keyword 

leam_sequence 

marker 

pattern 

process 

program 

range 

string 

unspecified 

window 


>) 


EXIT 


EXPAND_NAME (stringl ^ 


ALL 

KEYWORDS 
PROCEDURES 
, VARIABLES 


}) 


HELP_TEXT (library-file, topic | ’ buffer) 


INDEX (string, substring) 
integerl 


) 


{ mtegerl "j 
ke3word > 
string J 

JOURNAL_CLOSE 

JOURNAL_OPEN (file-name) 

LEARN ABORT 


LEARN_BEGIN ( 
LEARN END 


/ EXACT 
\ NO.EXACT 


LENGTH ( 


0 


buffer 
range 
string 

MESSAGE (buffer, range I, integerll) 

{ integer2 "j 
keyword h,i 
string J 

QUIT K { Qpp }l[ . severityl) 1 

READ.CHAR 

READ_KEY 

READ_LINE I (stringl E , integer]))]] 
SET (EOB.TEXT, buffer, string) 


integers E, FAO-parameter]]])) 
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VAXTPU Built-In Procedures 

Built-In Procedures Grouped According to Function 






• SLEEP ( ( 

\ stnng J 

• STR (integer) 

• STR( I {“J 

[ stringl 

r buffer ^ 

• SUBSTR ( < range > , integerl |[, integer2 I) 

( stringl J 


, ON 
, OFF 


Descriptions of the Built-In Procedures 

The discussion of each built-in procedure in this section is divided, as 
applicable, into the following parts: 

• A short functional definition 

• Format 

• Parameters 

• Description 

• Signaled Errors listing the warnings and errors signaled, if applicable 

• Examples 

The built-in procedures are presented in alphabetical order. 
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ABORT 


ABORT 

Stops any executing procedures and causes VAXTPU to wait for the next key 
press. 

FORMAT 

ABORT 

PARAMETERS 

None. 

DESCRIPTION 

ABORT returns control to VAXTPU’S main control loop. It causes an 
immediate exit from all invoked procedures. 

Although ABORT behaves much like a built-in, it is actually a VAXTPU 
language element. 

ABORT is evaluated for correct syntax at compile time. In contrast, 
VAXTPU procedures are usually evaluated for a correct parameter count 
and parameter types at execution time. 

SIGNALED 

ERRORS 

ABORT is a language element and has no completion codes. 


EXAMPLE 

ON_ERROR 

MESSAGE ("Aborting command because of error."); 
ABORT; 


ENDON_ERROR; 

This error handler does not try to recover from an error. Rather, it stops 
execution of the current procedure and returns to VAXTPU’S main loop. 
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ADD_KEY_MAP 


ADD KEY MAP 



Adds one or more key maps to a key map list. 

FORMAT 

ADD_KEY_MAP (key-map-list-name, | | key-map-name [, ... ]) 

PARAMETERS 

key-map‘Ust-name 

A string that specifies the name of the key map list. 

"first” 

A string directing VAXTPU to add the key map to the beginning of the key 
map list. In cases where a key is defined in multiple key maps, the first 
definition found for that key in any of the key maps in a key map list is 
used. 

last” 

A string directing VAXTPU to add the key map to the end of the key 
map hst. In cases where a key is defined in multiple key maps, the first 
definition found for that key in any of the key maps in a key map hst is 
used. 

key-map-name 

A string that specifies the name of the key map to be added to the key 
map list. You can specify more than one key map. Key maps are added to 
the key map list in the order specified. The order of a key map in a key 
map list determines precedence among any conflicting key definitions. 

DESCRIPTION 

The built-in procedure ADD_KEY_MAP adds key maps to key map lists. 
Key maps are added, in the order specified, to either the top or the bottom 
of the key map list. Key map precedence in a key map list is used to 
resolve any conflicts between key definitions. The key definition in a 
preceding key map overrides any conflicting key definitions in key maps 
that follow in the key map list. 

See the descriptions of the built-in procedures DEFINE_KEY, CREATE^ 
KEY__MAP, and CREATE_KEY__MAP_LIST for more information on 
key definitions, key maps, and key map lists, respectively. Also see the 
description of the built-in procedure REMOVE_KEY_MAP for information 
on removing key maps from a key map list. 
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ADD KEY MAP 


SIGNALED 

ERRORS 


TPU$_NOKEYMAP 

WARNING 

Third argument is not a defined 
key map. 

TPU$_KEYMAPNTFND 

WARNING 

The key map listed in the third 
argument is not found. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
ADD_KEY__MAP built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the ADD_KEY_MAP built-in. 

TPU$_NOKEYMAPLlST 

WARNING 

Attempt to access an undefined 
key map list. 

TPU$JNVPARAM 

ERROR 

Wrong type of data sent to the 
ADD_KEY_MAP built-in. 

TPU$JLLREQUEST 

WARNING 

The position string must be either 
"first' or "last". 

TPU$_BADREQUEST 

WARNING 

The position string must be either 


"f/rsf" or "/asf". 


EXAMPLES 

D ADD_KEY_MAP ("TPU$KEY_MAP__LIST", "last", "TPU$KEY_MAP"); 

This statement adds the default key map TPU$KEY_MAP to the default 
key map list, TPU$KEY_MAP_LIST. Normally (except in the EVE editor) 
TPU$KEY_MAP is a member of the default key map list. 

g help_keys := CREATE_KEY_MAP ("help_keys"); 

ADD_KEY_MAP ("TPU$KEY_MAP_LIST", "first", help_keys); 

These statements create a key map called HELP_KEYS and add it to 
the beginning of the default key map list, TPU$KEY_MAP_LIST. Key 
definitions in the new key map are invoked over definitions in the key 
maps already in the list. 
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ADJUST_WINDOW 


ADJUST_WINDOW 



Changes the size and/or screen location of a window and makes the window 
that you specify the current window. 

FORMAT 

ADJUST_WINDOW (window, integerl, integer2) 

PARAMETERS 

window 

The window whose size or location you want to change. The window that 
you specify becomes the current window, and the buffer mapped to that 
window becomes the current buffer. 

integerl 

The signed integer value that you add to the screen line number at the top 
of the window. 

integer2 

The signed integer value that you add to the screen line number at the 
bottom of the window. 

DESCRIPTION 

If you want to check the visible size and/or location of a window before 
making an adjustment to it, use any of the following statements: 

SHOW (WINDOW): 

SHOW (WINDOWS): 

top := GET INFO (window, "top", VISIBLE WINDOW): 

MESSAGE (STR (top)): 

bottom := GETJNFO (window, "bottom", VISIBLE WINDOW): 

MESSAGE (STR (bottom)): 

There are screen line numbers at both the top eind the bottom of the 
visible window. Adjust the size of a visible window by changing either or 
both of these screen line numbers. Make these changes by adding to or 
subtracting from the current screen line number, not by specifying the 
screen line number itself. 

You can enlarge a window by decreasing the screen line number at the 
top of the window. (Specify a negative value for integerl.) You can also 
enlarge a window by increasing the screen line number at the bottom of 
the window. (Specify a positive value for integer2.) The following example 
adds four lines to the current window, provided that the values fall within 
the screen boundaries: 

ADJUST_WINDOW (CURRENT_WINDOW, -2, +2) 
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ADJUST_WINDOW 


If you specify integers that attempt to set the screen hne number beyond 
the screen boundaries, VAXTPU issues a warning message. VAXTPU then 
sets the window boundary at the edge (top or bottom, as appropriate) of 
the screen. 

You reduce a window by increasing the screen line number at the top 
of the window. (Specify a positive value for integerl.) You can also reduce 
a window by decreasing the screen line number at the bottom of the 
window. (Specify a negative value for integer2.) If you attempt to make 
the size of the window smaller than one line (two lines if the window has 
a status line, three lines if the window has a status line and a horizontal 
scroll bar), VAXTPU issues an error message and no adjustment occurs. 
The following example reduces the current window by four lines: 

ADJUST_WINDOW (CURRENT_WINDOW, +2, -2) 

You can also use AD JUST_WINDOW to change the position of the window 
on the screen without changing the size of the window. The following 
command simply moves the current window two lines higher on the 
screen, provided that the values fall within the screen boundaries: 

ADJUST_WINDOW (CURRENT_WINDOW, -2, -2) 

Figure 7-1 shows a screen layout when you invoke VAXTPU with EVE 
and a user-written command file. In this case, the user-written command 
file divides the screen into two windows. The top window has 15 text 
lines (including the end-of-buffer message) and a status line. The bottom 
window has five text lines and a status line. The two bottom lines of the 
screen are the command window and message window, each consisting of 
one line. 
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ADJUST WINDOW 


Figure 7-1 Screen Layout Before Using ADJUST_WiNDOW 



ZK-4047-GE 


The user-written command file uses the variable secondjtvindow to identify 
the bottom window. Figure 7-2 shows the screen layout after the user 
enters ADJUST_WINDOW (second_window, —5, 0) after the appropriate 
prompt from EVE. Both the top and bottom windows now contain 10 lines 
of text and a status line. Note that the cursor is now located in the bottom 
window. The command and message windows still contain one line each. 

ADJUST_WINDOW adds (+/-) integerl to the “visible_top” and (+/-) 
integer2 to the “visible_bottom” of a window. The mapping of the window 
to its buffer is not changed. The new values for the screen line numbers 
become the values for the original top and original bottom. (See Chapter 2 
for more information on window dimensions and window values.) 
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ADJUST WINDOW 


Figure 7-2 Screen Layout After Using ADJUST_WINDOW 


First line 
Second line 
Third line 
Fourth line 
Fifth line 
Sixth line 
Seventh line 
Eighth line 
Ninth line 
Tenth line 


Buffer MAIN 


Jirst line 
Second line 
Third line 
Fourth line 
Fifth line 
Sixth line 
Seventh line 
Eighth line 
Ninth line 
Tenth line 


Buffer SECOND BUFFER 
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Using ADJUST_WINDOW on a window makes it the current window; that 
is, VAXTPU puts the cursor in that window if the cursor was not already 
there, and VAXTPU marks that window as current in VAXTPU’s internal 
tracking system. VAXTPU may scroll or adjust the text in the window to 
keep the current position visible after the adjustment occurs. 

Note that both ADJUST_WINDOW and MAP may split or occlude other 
windows. 

If you execute ADJUST_WINDOW within a procedure, the screen is not 
immediately updated to reflect the adjustment. The adjustment is made 
after the entire procedure is finished executing and control returns to 
the screen manager. If you want the screen to reflect the adjustment to 
the window before the entire procedure is executed, you can force the 
immediate update of a window by adding an UPDATE statement to the 
procedure. See the built-in procedure UPDATE for more information. 

If you have defined a top or bottom scroll margin, and the vdndow is 
adjusted so that the scroll margins no longer fit, TPU$_ADJSCROLLREG 
is signaled and the scroll margins shrink proportionally. For example, if 
you have a ten-line window, with an eight-line top scroll margin, shrinking 
the window to a five-line window also reduces the top scroll margin to four 
lines. 
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ADJUST WINDOW 


SIGNALED 

ERRORS 

TPU$_ADJSCROLLREG 

INFO 

The window’s scrolling region 
has been adjusted to fit the new 
window. 


TPU$_BOTLINETRUNC 

INFO 

Bottom line cannot exceed bottom 
of screen. 


TPU$_TOPLINETRUNC 

INFO 

Top line cannot exceed top of 




screen. 


TPU$_WINDNOTMAPPED 

WARNING 

Cannot adjust a window that is 
not mapped. 


TPU$_BADWINDADJUST 

WARNING 

Cannot adjust window to less than 
the minimum number of lines. 


TPU$_WINDNOTVIS 

WARNING 

No adjustment if window Is not 
visible. 


TPU$_TOOFEW 

ERROR 

You specified less than three 
parameters. 


TPU$_TOOMANY 

ERROR 

You specified more than three 
parameters. 


TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 

EXAMPLES 




D ADJUST_WINDOW 

(CURRENT_WINDOW, +5, 0) 




This statement reduces the current window by removing five lines from the 
top of the window. If the top line of the window is screen line number 11, 
this statement changes the top line of the window to screen line number 
16. (If the bottom line of the window is less than screen line number 16, 
VAXTPU signals an error.) 

§ PROCEDURE user_display_help 

top_of_window := GET_INFO (CURRENT_WINDOW, "VISIBLE_TOP*'); 

I 

! Remove the top five lines from the current window 
! and replace them with a help window 

j 

ADJUST_WINDOW (CURRENT_WINDOW, +5, 0) ; 

example_window := CREATE_WINDOW (top_of_window, 5, ON); 
example_buffer := CREATE_BUFFER ("EXAMPLE", 

"sys$login:template.txt"); 

MAP (example_window, example__buf fer) ; 

ENDPROCEDURE; 

This procedure removes five lines from the top of a window and puts a 
help window in their place. 
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ANCHOR 

Forces the next pattern element either to match immediately or else to fail. 

FORMAT 

ANCHOR 

PARAMETERS 

None. 

DESCRIPTION 

Normally, when SEARCH fails to find a match for a pattern, it retries the 
search. To try again, the SEARCH built-in moves the starting position 
one character forward or backward, depending upon the direction of the 
search. SEARCH continues this operation imtil it either finds a match 
for the pattern or reaches the end or beginning of the buffer or range 
being searched. If ANCHOR appears as the first element of a complex 
pattern, the search does not move the starting position. Instead, the 
search examines the next (or previous) character to determine if it matches 
the next character or element in the complex pattern. If the pattern does 
not match starting in the original position, the search fails. SEARCH does 
not move the starting position and retry the search. 

When you build complex patterns using the + operator rather than the & 
operator, ANCHOR is useful only as the first element of a complex pattern. 
It is legal elsewhere in a pattern but has no effect. 

Although ANCHOR behaves much like a built-in, it is actually a ke3rword. 

For more information on patterns or modes of pattern searching, see 
Chapter 2. 

SIGNALED 

ERRORS 

ANCHOR is a keyword and has no completion codes. 


EXAMPLES 

Q patl := ANCHOR + "al23"; 

This assignment statement creates a pattern that matches the string al23. 
Because ANCHOR appears as the first element of the pattern, SEARCH 
will find al23 only if the string appears at the starting position for the 
search. 
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§ PROCEDURE user_remove_comments 
LOCAL patl, 

numbe r__removed, 
end_mark; 
patl := ANCHOR + 
number_removed := 0; 
end_mark := END_OF (CURRENT_BUFFER); 

POSITION (BEGINNING_OF (CURRENT_BUFFER)); 

LOOP 

EXITIF MARK (NONE) = end_mark; 

rl := SEARCH_QUIETLY (patl, FORWARD); 

IF rl <> 0 

THEN ! comment found so erase it 

ERASE_LINE; 

number_removed := number_removed + 1; 

ENDIF; 

MOVE_VERTICAL (1); ! move to the next line 

ENDLOOP; 

MESSAGE (FAO (”!ZL comment!%S removed.”, number_removed)); 

ENDPROCEDURE; ” 

This procedure starts at the beginning of a buffer and searches forward, 
removing all comments that begin in column 1. The keyword ANCHOR 
in this example ties the search to the first character of a line (the current 
character). This prevents the search function from finding and removing 
exclamation points in the middle of a line (for example, in the FAO 
directive, !AS). 
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ANY 

Returns a pattern that matches one or more characters from the set specified. 

FORMAT 

( buffer ] 

pattern := ANY ( < range > [, integerl ]) 

[ string ) 

PARAMETERS 

buffer 

An expression that evaluates to a buffer. ANY matches any of the 
characters in the resulting buffer. 

range 

An expression which evaluates to a range. ANY matches any of the 
characters in the resulting range. 

String 

An expression that evaluates to a string. ANY matches any of the 
characters in the resulting string. 

integerl 

This integer value indicates how many contiguous characters ANY 
matches. The default value for this integer is 1. 

return value 

A pattern matching one or more characters that appear in the string, 
buffer, or range passed as the first parameter to ANY. 

DESCRIPTION 

ANY is used to construct patterns. 

SIGNALED 

ERRORS 

TPU$_NEEDTOASSIGN ERROR ANY must appear in the right-hand 

side of an assignment statement. 

TPU$_TOOFEW ERROR ANY requires at least one 

argument. 

TPU$_TOOMANY ERROR ANY accepts no more than two 

arguments. 

TPU$_ARGMISMATCH ERROR The argument you passed to the 

ANY built-in was of the wrong 


type. 
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TPU$JNVPARAM 

ERROR 

The argument you passed to the 
ANY built-in was of the wrong 
type. 

TPU$_MINVALUE 

WARNING 

The argument you passed to the 
ANY built-in was less than the 
minimum accepted value. 

TPU$_CONTROLC 

ERROR 

You pressed CTRLVC during the 
execution of the ANY built-in. 


EXAMPLES 

D patl := ANY ("hijkl") 

This assignment statement creates a pattern that matches any one of the 
characters h, ij, k, and L 

§ patl := any ("xy", 2); 

This assignment statement creates a pattern that matches any of the 
following two-letter combinations: xx, xy, yx, and yy, 

g a_buf := CREATE_BUFFER ("new buffer"); 

POSITION (a_buf); 

COPY_TEXT ("xy"); 

SPLIT_LINE; 

COPY_TEXT ("abc"); 
patl := ANY (a_buf); 

These statements create a pattern that matches any one of the characters 
a, 6, c, X, and y. 

Q PROCEDURE user__find_endprocedure 
LOCAL endprocedure_pattern, 
search_range; 

endprocedure_pattern := (LINE_BEGIN + "ENDPROCEDURE") + 

(LINE_END I ANY (";! " + ASCII (9))); 
search_range := SEARCH_QUIETLY (endprocedure_pattern, FORWARD); 

IF search_range = 0 
THEN 

MESSAGE ("Endprocedure statement not found"); 

ELSE 

POSITION (END__OF (search_range) ) ; 

ENDIF; 

ENDPROCEDURE; 

This procedure finds an ENDPROCEDURE statement that starts in 
column 1 and moves the editing point to the end of the statement. 
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APPEND LINE 



Places the current line at the end of the previous line. 

FORMAT 

APPEND_LINE 

PARAMETERS 

None. 

DESCRIPTION 

You can use APPEND_LINE to delete line terminators. 

The editing point in the line that was the current line before APPEND_ 
LINE was executed becomes the editing point. 

Using APPEND_LINE may cause VAXTPU to insert padding spaces or 
blank lines in the buffer. APPEND_LINE causes the screen manager 
to place the editing point at the cursor position if the current buffer is 
mapped to a visible window. (For more information on the distinction 
between the cursor position and the editing point, see Chapter 6.) If the 
cursor is not located on a character (that is, if the cursor is before the 
beginning of a line, beyond the end of a line, in the middle of a tab, or 
below the end of the buffer), VAXTPU inserts padding spaces or blank 
lines into the buffer to fill the space between the cursor position and the 
nearest text. 

SIGNALED 

ERRORS 

TPU$_NOCURRENTBUF WARNING You are not positioned in a buffer. 

TPU$_NOCACHE ERROR There is not enough memory to 

allocate a new cache. 

TPU$_TOOMANY ERROR APPEND_LINE does not accept 

arguments. 

TPU$_NOTMODIFIABLE WARNING You cannot modify an unmodifiable 

buffer. 

TPU$_LINETOOLONG WARNING VAXTPU cannot append the line 

because the length of the resulting 
line would exceed VAXTPU’s 
maximum line length. 


EXAMPLES 


Q APPEND_LINE 

This statement adds the current line to the end of the previous line. 
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The following procedure deletes the character 
to the left of the cursor. If the cursor is at the 
beginning of a line, it appends the current line 
to the end of the previous line. 


PROCEDURE user__delete_char 
IF CURRENT_OFFSET = 0 
THEN 

APPEND_LINE; 

ELSE 

ERASE_CHARACTER (-1); 

ENDIF; 

ENDPROCEDURE; 


This procedure deletes the character to the left of the cursor. If you are at 
the beginning of a line, the procedure appends the current line to the end 
of the previous line. The procedure works correctly even if the window is 
shifted. 

You can bind this procedure to the DELETE key with the following 
statement: 


DEFINE_KEY ("user_delete_char’', DEL KEY); 
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ARB 

Returns a pattern that matches an arbitrary sequence of characters starting at 
the editing point and extending for the length you specify. 

FORMAT 

pattern := ARB (integer) 

PARAMETER 

integer 

The number of characters in the pattern. This integer must be positive. 

return value 

A pattern that matches an arbitrary sequence of characters starting at the 
editing point and extending for the length you specify. 

DESCRIPTION 

ARB can be used for wildcard matches of fixed length. 

For more information on patterns, see Chapter 2. 

SIGNALED 

ERRORS 

TPU$_NEEDT0ASS1GN ERROR ARB must appear in the right-hand 

side of an assignment statement. 

TPU$_TOOFEW ERROR ARB requires at ieast one 

argument. 

TPU$_TOOMANY ERROR ARB accepts no more than one 

argument. 

TPU$JNVPARAM ERROR The argument to ARB must be an 

integer. 

TPU$_MIN\/ALUE WARNING The argument to ARB must be 

positive. 


EXAMPLES 

Q patl := ARB (5) 

This assignment statement creates a pattern that matches the next five 
characters starting at the editing point. The characters themselves are 
arbitrary; it is the number of characters that is important for a pattern 
created with ARB. 

I pat2 := "J" & ARB (2) 

This assignment statement creates a pattern that matches a string 
beginning with a J and followed by any two other characters. Names 
such as “Jim,” “Jan,” and “Joe” match pat2. 
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S PROCEDURE user_replace_prefix 
LOCAL cur_mode^ 
here, 
patl, 

found_range; 


patl := (LINE_BEGIN | NOTANY ("ABCDEFGHIJKLMNOPQRSTUVWXYZ_$")) 
+ ((ARB (3) + 0 found_range); 

here := MARK (NONE); 

cur_mode := GET_INFO (current_buffer, "mode"); 


POSITION (BEGINNING__OF (CURRENT_BUFFER) ) ; 
LOOP 


found_range := 0; 

SEARCH_QUIETLY (patl, FORWARD); 
EXITIF found^range = 0; 

ERASE (found_range); 

POSITION (END_OF (found_range)); 
COPY_TEXT ("user_"); 

ENDLOOP; 

POSITION (here); 

SET (cur_mode, current__buf fer) ; 
ENDPROCEDURE; 


This procedure replaces a prefix of any three characters followed by an 
underscore (xxx_) in the current buffer with the string "user_". It does not 
change the current position. 
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ASCII 

Returns the ASCII value of a character or the character that has the specified 
ASCII value. 

FORMAT 

1 S’ 

/ 

PARAMETERS 

integerl 

The decimal value of a character in the DEC Multinational Character Set. 

keyword 

This ke 3 rword must be a key name. If the key name is the name of a 
key that produces a printing character, ASCII returns that character. 
Otherwise it returns the character whose ASCII value is 0. 

String 1 

The character whose ASCII value you want. If the string has a length 
greater than 1, the ASCII built-in returns the ASCII value of the first 
character in the string. 

return value 

The character with the specified ASCII value (if you specify an integer or 
keyword parameter). 

The ASCII value of the string you specify (if you specify a string 
parameter). 

DESCRIPTION 

The result of this built-in depends upon its argument. If the argument is 
an integer then it returns a string of length 1 that represents the character 
of the DEC Multinational Character Set corresponding to the integer you 
specify. If the argument is a string then it takes the first character of the 
string and returns the integer corresponding to the ASCII value of that 
character. 

If the argument to ASCII is a keyword, that ke 3 rword must be a key name. 
The VAXTPU built-in KEY_NAME produces key names. In addition, there 
are several predefined kejnvords that are key names. See Table 2-1 for a 
list of these keywords. If the keyword is a key name and the key produces 
a printing character, ASCII returns that character; otherwise, it returns 
the character whose ASCII value is 0. 
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SIGNALED 

ERRORS 


TPU$_NEEDTOASSIGN 

ERROR 

ASCII must be on the right-hand 
side of an assignment statement. 

TPU$_TOOFEW 

ERROR 

ASCII requires one argument. 

TPU$_TOOMANY 

ERROR 

ASCII accepts only one argument. 

TPU$_ARGMISMATCH 

ERROR 

The parameter you passed to 
ASCII is of the wrong type. 

TPU$_NULLSTRING 

WARNING 

You passed a string of length 0 to 
ASCII. 


EXAMPLES 


my character 


ASCII (12) 

This assignment statement assigns a string of length 1 to the variable 
my^character. This string contains the form feed character because that 
character has the ASCII value 12. 


MESSAGE (ASCII (80)) 


This statement combines two built-in procedures and prints the ASCII 
character numbered 80 (whose value is P) in the message area. In this 
case, uppercase P is displayed. 


! This procedure puts a tab character in your text 

j 

PROCEDURE user_tab 

COPY_TEXT (ASCII (9)); 

ENDPROCEDURE; 


This procedure includes a tab character in the current buffer. 


Q ascii__value 




ASCII ("a"); 

This assignment statement assigns the integer value 97 to the variable 
asciijualue. Note that a is specified in quotation marks because it is a 
parameter of type string. For more information on specifying strings, see 
Chapter 2. 
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§ PROCEDURE user_test_key 
LOCAL key_struck, 
key__value; 

MESSAGE ("Press a key"); 
key_struck := READ_KEY; 
key_value := ASCII (key_struck); 

IF key_value = ASCII (0) 

THEN 

MESSAGE ("That is not a typing key"); 

ELSE 

MESSAGE (FAO ("That key produces the letter "!AS".", key_value)); 

ENDIF; 

ENDPROCEDURE; 

This procedure prompts the user to press a key. When the user does 
so, the procedure reads the key. If the key is associated with a printing 
character, ASCII tells the user what character is produced. If the key is 
not associated with a printable character, ASCII informs the user of this. 
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ATTACH 

Enables you to switch control from your current process to another process 
that you have previously created. 

FORMAT 


PARAMETERS 

integer 

This integer is the process identification (PID) of the process to which 
terminal control is to be switched. You must use decimal numbers to 
specify the PID to VAXTPU. 

String 

A quoted string, a variable name representing a string constant, or an 
expression that evaluates to a string that VAXTPU interprets as a process 
name. 

DESCRIPTION 

To use the built-in procedure ATTACH, you must have previously created 
a subprocess. If the process you specify is not part of the current job or 
does not exist, an error message is displayed. For information on creating 
subprocesses, see the description of SPAWN in this section. 

ATTACH suspends the current VAXTPU process and switches context to 
the process you use as a parameter. If you do not specify a parameter 
for ATTACH, VAXTPU switches control to the parent or owner process. 

A subsequent use of the DCL command ATTACH (or a logout from any 
process except the parent process) resumes the execution of the suspended 
VAXTPU process. 

In all cases, VAXTPU first deassigns the terminal. If a VAXTPU process 
is resumed following a SPAWN or ATTACH command, VAXTPU reassigns 
the terminal and refreshes the screen. 

If the current buffer is mapped to a visible window, the ATTACH built-in 
causes the screen manager to synchronize the editing point, which is a 
buffer location, with the cursor position, which is a window location. This 
may result in the insertion of padding spaces or lines into the buffer if the 
cursor position is before the beginning of a line, in the middle of a tab, 
beyond the end of a line, or after the last line in the file. 

ATTACH is not a valid built-in in DECwindows VAXTPU. However, if 
you are running non-DECwindows VAXTPU in a DECwindows terminal 
emulator, ATTACH works as described in this section. 
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SIGNALED 

ERRORS 


TPU$_NOPARENT 

WARNING 

There is no parent process to 
which you can attach — your 
current process is the top-level 



process. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the ATTACH built-in. 

TPU$_SYSERROR 

ERROR 

Error requesting information about 
the process being attached to. 

TPU$_ARGMISMATCH 

ERROR 

Wrong type of data sent to the 
ATTACH built-in. Only process 
name strings and process IDs are 
allowed. 

TPU$_CREATEFAIL 

WARNING 

Unable to attach to the process. 

TPU$_REQUIRESTERM 

ERROR 

Feature requires a terminal. 


EXAMPLES 

Q ATTACH 

This statement causes VAXTPU to attach to the parent process. 

g ATTACH (97899) 

This statement causes VAXTPU to attach to the subprocess with the PID 
97899. 

g ATTACH ("J0NES_2") 

This statement switches the terminal’s control to the process JONES_2. 
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BEGINNING. 

_OF 

Returns a marker that points to the first position of a buffer or a range. 

FORMAT 

marker := BEGINNING OF { [ 1; 

- ' \ range y 

PARAMETERS 

buffer 

The buffer whose beginning you want to mark. 

range 

The range whose beginning you want to mark. 

return value 

A marker pointing to the first character position of the specified buffer or 
range. 

DESCRIPTION 

If you use the marker returned by this built-in procedure as a parameter 
for the built-in procedure POSITION, the editing point moves to the 
marker. 

SIGNALED 

ERRORS 

TPU$_NEEDTOASSIGN ERROR BEGINNING_OF must appear 

in the right-hand side of an 
assignment statement. 

TPU$_TOOFEW ERROR BEGINNING.OF requires one 

argument. 

TPU$_TOOMANY ERROR BEGINNING_OF accepts only one 

argument. 

TPU$_ARGMISMATCH ERROR You passed something other 

than a range or a buffer to 
BEGINNING_OF. 


EXAMPLES 

D beg_main := BEGINNING_OF (main_buffer) 

This assignment statement stores the marker that points to the beginning 
of the main buffer in the variable begjnain, 

g POSITION (BEGINNING_OF (my_range)) 

This statement uses two built-in procedures to move your current 
character position to the beginning of my_range. If myjrange is in a 
visible buffer in which the cursor is located, the cursor position is also 
moved to the beginning of myjrange. 
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PROCEDURE user_top 

IF MARK (NONE) = BEGINNING_OF (CURRENT_BUFFER) 
THEN 

MESSAGE ("Already at top"); 

ELSE 

POSITION (BEGINNING_OF (CURRENT_BUFFER)); 
ENDIF; 

ENDPROCEDURE; 


This procedure places the cursor at the beginning of the current buffer. If 
you are already at the beginning of the buffer, the message "Already at 
top" is displayed in the message area. 

Q PROCEDURE user_include_file 
! Create scratch buffer 

bl := CREATE_BUFFER ("Scratch Buffer"); 

! Map scratch buffer to main window 
MAP (main_window, bl); 

! Read in file name given 

READ__FILE (READ_LINE ("File to Include:" )); 

! Go to top of file 

POSITION (BEGINNING_OF (bl)); 

ENDPROCEDURE; 


This procedure creates a new buffer, associates the buffer with the main 
window, and maps the main window to the screen. It positions to the top 
of the buffer, prompts the user for the name of a file to include, and reads 
the file into the buffer. 
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BREAK 

Activates the debugger if VAXTPU was invoked with the /DEBUG qualifier. 

FORMAT 

BREAK 

PARAMETERS 

None. 

DESCRIPTION 

If VAXTPU was invoked with the /DEBUG qualifier, then execution of the 
BREAK statement activates the debugger. If there is no debugger, BREAK 
causes the following message to be displayed in the message window: 

Breakpoint at line xxx 

It has no other effect. Although BREAK behaves much like a built-in, it is 
actually a VAXTPU language element. 

BREAK is evaluated for correct syntax at compile time. In contrast, 
VAXTPU procedures are usually evaluated for a correct parameter count 
and parameter types at execution time. 

SIGNALED 

ERROR 

BREAK is a language element and has no completion codes. 


EXAMPLE 

PROCEDURE user_not_quite_working 

BREAK; 


ENDPROCEDURE; 

This procedure contains a break statement. If the statement is executed, 
VAXTPU’S debugger is activated, allowing the user to debug that section 
of the code. 
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CALL USER 



Calls a program written in another language from within VAXTPU. The CALL_ 
USER parameters are passed to the external routine exactly as you enter 
them; VAXTPU does not process the parameters in any way. The integer is 
passed by reference, and string 1 is passed by descriptor. String2 is the value 
returned by the external program. 

FORMAT 

string2 := CALL_USER (integer, stringl) 

PARAMETERS 

integer 

The integer that is passed to the user-written program by reference. 

stringl 

The string that is passed to the user-written program by descriptor. 

return value 

The value returned by the called program. 

DESCRIPTION 

In addition to returning the value string2 to CALL_USER, the external 
program returns a status code that tells whether the program executed 
successfully. You can trap this status code in an ON_ERROR statement. 
An even-numbered status code (low bit in RO clear) causes the ON_ERROR 
statement to be executed. The ERROR lexical element returns the status 
value from the program in the form of a keyword. 

To use the built-in procedure CALL_USER, follow these steps: 

• Write a program in whatever language you choose. The program must 
be a global routine called TPU$CALLUSER. 

• Compile the program. 

• Link the program with an options file to create a shareable image. 

• Define the logical name TPU$CALLUSER to point to the file 
containing your routine. 

• Invoke VAXTPU. 

• From within a VAXTPU session, call your external program to perform 
its function by specifying the built-in procedure CALL_USER with the 
appropriate parameters. If you link your program properly, and if you 
define the logical name TPU$CALLUSER to point to your program, 
the built-in procedure CALL_USER passes the parameters you give it 
to the proper routine. 
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The CALL_USER parameters are input parameters for the external 
program you are calling. VAXTPU does not process the parameters in 
any way but passes them to the external procedure exactly as you enter 
them. You must supply both parameters even if the routine you are calling 
does not require that information be passed to it. Enter the following null 
parameters to indicate that you are not passing any actual values: 

CALL_USER (0,"") 

For information on the VAXTPU callable interface, see the VMS Utility 
Routines Manual. 


SIGNALED 

ERRORS 

TPU$_BADUSERDESC 

ERROR 

User-written routine incorrectly 
filled in the return descriptor. 


TPU$_NOCALLUSER 

ERROR 

Could not find a routine to invoke. 


TPU$_TOOFEW 

ERROR 

Too few arguments passed to 
CALL.USER. 


TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
CALL_USER. 


TPU$_NEEDTOASSIGN 

ERROR 

The call to CALL__USER must 
be on the right-hand side of the 
assignment statement. 


TPU$JNVPARAM 

ERROR 

Wrong type of data sent to CALL_ 
USER. 


TPU$_ARGM1SMATCH 

ERROR 

Parameter is of the wrong data 
type. 


TPU$_CALLUSERFAIL 

WARNING 

CALL_USER routine failed with 


status %X’status’. The value 
returned by ERROR after this type 
of error will be the status value 
reported by this message. 


EXAMPLES 

D ret_value := CALL_USER (6, "ABC") 

This statement calls a program that the user wrote. Before invoking 
VAXTPU,the user created a logical name, TPU$CALLUSER, that points 
to the file containing the program the user wants called by CALL_USER. 
VAXTPU passes the first parameter (6) by reference, and the second 
parameter (“ABC”) by descriptor. If, for example, the user program uses 
an integer and a string as input values, the program processes the integer 
“6” and the string "ABC." If the program is designed to return a result, 
the result is returned in the variable ret_value. 
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§ step-by-step Example of Using CALL_USER 

The following example shows the steps required to use the built-in 
procedure CALL_USER. The routine that is called to do floating-point 
arithmetic is written in BASIC. 

1 Write a program in BASIC that does floating-point arithmetic on the 
values passed to it. 


! FilenameiFLOATARITH.BAS 


1 

10 

20 


999 


sub TPU$CALLUSER ( some_integer% , input_string$ ^ return_string$ ) 

! don't check some_integer% because this function only does 
! floating-point arithmetic 

! parse the input string 
! find and extract the operation 
comma_location = pos ( input_string$, "r", 1% ) 
if comma_location = 0 then go to all_done 
end if 

operation$ = seg$( input_string$, 1%, comma_location - 1% ) 

! find and extract the 1st operand 

operandl_location = pos ( input_string$, comma_location +1 ) 

if operandl_location = 0 then go to all_done 
end if 

operandl$ = seg$( input_string$, comma_location + 1% , & 

operandl_location -1 ) 

! find and extract the 2nd operand 

operand2_location = pos ( input_string$, operandl_location +1 ) 

if operand2_location = 0 then 

operand2_location = len( input_string$) + 1 

end if 


operand2$ = seg$( input_string$/ operandl__location + 1% , & 

operand2_location -1 ) 


select operation$ ! do the operation 
case 

result$ = sum$( operandl$ , operand2$ ) ! 


case 

result$ = 

case 

result$ = 

case "/" 

result$ = 

case else 

result$ = 
end select 


dif$( operandl$, operand2$ ) ! 

numl$( Val( operandl$ ) * Val( operand2$ 
numl$( Val( operandl$ ) / Val( operand2$ 
"unknown operation." 


) 

) 


return_string$ = result$ 
all done: end sub 


2 Compile the program with the following statement: 


$ BASIC/LIST floatarith 
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3 Create an options file to be used by the linker when you link the 
BASIC program. 


+ 


File: FLOATARITH.OPT 


Options file to link floatarith BASIC program with VAXTPU 


floatarith.obj 
UNIVERSAL=TPU$CALLUSER 


4 Link the program (using the options file) to create a shareable image. 


$ LINK floatarith/SHARE/OPT/MAP/FULL 

5 Define the logical name TPU$CALLUSER to point to the executable 
image of the BASIC program. 

$ DEFINE TPU$CALLUSER device:[directory]floatarith.EXE 



6 Invoke VAXTPU. 

7 Write and compile the following VAXTPU procedure: 


PROCEDURE my_call__user 

! test the built-in procedure call_user 

LOCAL output, 
input; 

input := READ_LINE ("Call user >"); ! Provide a parameter for routine 

output := CALL_USER ( 0, input); ! Value this routine returns 

MESSAGE (output); 

ENDPROCEDURE; 




8 When you call the procedure myj 2 all_user, you are prompted for 

parameters to pass to the BASIC routine. The order of the parameters 
is operator, number, number. For example, if you enter “+, 3.33, 4.44” 
after the prompt, the result 7.77 is displayed in the message area. 
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CHANGE CASE 


Changes the case of all alphabetic characters in a buffer, range, or string, 
according to the keyword that you specify. Optionally, CHANGE_CASE 
returns a string, range, or buffer containing the changed text. 


FORMAT 


returned_buffer 1 

returned_range > := CHANGE_CASE 
returned_string J 


( buffer ] r INVERT \ 
(I range J, \ LOWER J 
[ string J [ UPPER ) 

T , IN_PLACE ]|, 

1 . NOT_IN_PLACE ^ 


PARAMETERS buffer 

The buffer in which you want VAXTPU to change the case. Note that you 
cannot use the keyword NOT_IN_PLACE if you specify a buffer for the 
first parameter. 

range 

The range in which you want VAXTPU to change the case. Note that you 
cannot use the ke 3 word NOT_IN_PLACE if you specify a range for the 
first parameter. 

String 

The string in which you want VAXTPU to change the case. If you specify 
IN_PLACE for the third parameter, CHANGE_CASE makes the specified 
change to the string specified in the first parameter. Note that if string is 
a constant, IN_PLACE has no effect. 

LOWER 

A kejnvord directing VAXTPU to change letters to all lowercase. 

UPPER 

A keyword directing VAXTPU to change letters to all uppercase. 

INVERT 

A keyword directing VAXTPU to change uppercase letters to lowercase and 
lowercase letters to uppercase. 

IN_PLACE 

A keyword directing VAXTPU to make the indicated change in the buffer, 
range, or string specified. This is the default. 

NOTJN_PLACE 

A keyword directing VAXTPU to leave the specified string unchanged 
and return a string that is the result of the specified change in case. You 
cannot use NOT_IN_PLACE if the first parameter is specified as a range 
or buffer. To use NOT_IN_PLACE, you must specify a return value for 
CHANGE_CASE. 
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return values 

returnedjbuffer 

A variable of type buffer pointing to the buffer containing the modified 
text, if you specify a buffer for the first parameter. The variable returned_ 
buffer points to the same buffer pointed to by the buffer variable specified 
as the first parameter. 

returnedjrange 

A range containing the modified text, if you specify a range for the first 
parameter. The returned range spans the same text as the range specified 
as a parameter, but they are two separate ranges. If you subsequently 
change or delete one of the ranges, this has no effect on the other range. 

retumed_string 

A string containing the modified text, if you specify a string for the first 
parameter. CHANGE_CASE can return a string even if you specify IN_ 
PLACE. 


Q£0QP|P'P|Q|Sj CHANGE_CASE modifies the case of all the alphabetic characters in the 

specified unit of text according to the keyword that you supply. 


SIGNALED 

ERRORS 


TPU$_TOOFEW 

ERROR 

CHANGE_CASE requires two 
parameters. 

TPU$_TOOMANY 

ERROR 

CHANGE_CASE accepts only two 
parameters. 

TPU$_ARGMISMATCH 

ERROR 

One of the parameters to 
CHANGE_CASE is of the wrong 
data type. 

TPU$_INVPARAM 

ERROR 

One of the parameters to 
CHANGE_CASE is of the wrong 
data type. 

TPU$_BADKEY 

WARNING 

You gave the wrong keyword to 
CHANGE_CASE. 

TPU$_NOTMODIFIABLE 

WARNING 

You cannot change the case of 
text in an unmodifiable buffer. 

TPU$_CONTROLC 

ERROR 

You pressed CTRL/C during the 
execution of CHANGE_CASE. 


EXAMPLES 

Q CHANGE_CASE (CURRENT_BUFFER, UPPER) 

This statement makes all the characters in the current buffer uppercase. 
If you enter this statement on the command line of your interface, you see 
the effects immediately. If you use this statement within a procedure, you 
see the effect of the statement at the next screen update. 


7-45 








VAXTPU Built-In Procedures 

CHANGE CASE 


§ CHANGE_CASE (my_range, LOWER) 

This statement makes all the characters in my_range lowercase. If my_ 
range is part of a buffer that is mapped to a window, you see the command 
take effect immediately. 

@ PROCEDURE user_lowercase_line 
LOCAL this_line; 

this_line := ERASE_LINE; 

CHANGE_CASE (this_line, LOWER); 

SPLIT_LINE; 

MOVE_VERTICAL (-1); 

COPY_TEXT (this_line)/ 

ENDPROCEDURE; 

This procedure changes the current line to lowercase. 

Q PROCEDURE user__upcase_item 
ON_ERROR 

! In case no string is found during search 
MESSAGE ("No current item."); 

RETURN; 

ENDON_ERROR; 

delimiters := " " + ASCII(9); 

current_item := ANCHOR & SCAN (delimiters); 

item_range := SEARCH (current_item, FORWARD, NO_EXACT); 

CHANGE_CASE (item_range, UPPER); 

ENDPROCEDURE; 

This procedure puts the current text object in uppercase. 

g returned_value := CHANGE_CASE (CURRENT_BUFFER, LOWER, IN_PLACE); 

This statement makes all characters in the current buffer lowercase. The 
variable returnedjualue contains the newly modified current buffer. 

§ returned_value := CHANGE_CASE (the_string, INVERT, NOT_IN_PLACE); 

This statement inverts the case of all characters in the string pointed to by 
thejstring and returns the modified string in the variable returnedjualue. 
It does not change thejstring in any way. 
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COMPILE 

Converts VAXTPU procedures and statements into an internal, compiled 
format. Valid items for compilation can be represented by a string, a range, or 
a buffer. COMPILE optionally returns a program. 

FORMAT 

r buffer ] 

[ program := ] COMPILE ^ range V; 

[ string J 

PARAMETERS 

buffer 

A buffer that contains only valid VAXTPU declarations and statements. 

range 

A range that contains only valid VAXTPU declarations and statements. 

String 

A string that contains only valid VAXTPU declarations and statements. 

return value 

The program created by compiling the declarations and statements in the 
string, range, or buffer. If the program failed to compile, an integer zero is 
returned. 

DESCRIPTION 

The program that COMPILE optionally returns is the compiled form 
of valid VAXTPU procedures, statements, or both. You can assign 
the compiled version of VAXTPU code to a variable name. VAXTPU 
statements, as well as procedure definitions, can be stored in the program 
returned by COMPILE. Later in your editing session, you can execute the 
VAXTPU code that you compiled by using the program as a parameter 
for the built-in procedure EXECUTE. You can also use the program as 
a parameter for the built-in procedure DEFINE_KEY to define a key to 
execute the program. Then you can execute the program by pressing that 
key. 

COMPILE returns a program variable only if the compilation generates 
executable statements. COMPILE does not return a program variable if 
you compile any of the following: 

• Null strings or buffers 

• Procedure definitions that do not have any executable statements 
following them 

• Programs with syntax errors 

VAXTPU cannot compile a string, range, or line of text in a buffer longer 
than 256 characters. If VAXTPU encounters a longer string, range, or line, 
VAXTPU truncates characters after the 256th character and attempts to 
compile the truncated string, buffer, or range. 
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If necessary, use the built-in procedure SET (INFORMATIONAL, ON) 
before compiling a procedure interactively to see the compiler messages. 

To check the results of a compilation to determine whether execution is 
possible, use the following statement in a program: 

X := COMPILE (my__range) ; 

!if the program is nonzero, continue 

IF X <> 0 

THEN 


ENDIF; 

If X = 0, no program was generated because of compilation errors or 
because there were no executable statements. The statement “IF x <> 

0 THEN” allows your program to continue as long as a program was 
generated. 

You can also use an ON_ERROR statement to check the result of a 
compilation. This statement tells you whether the compilation completed 
successfully; it does not tell you whether execution is possible. You can use 
an ON_ERROR statement when compiling code consisting of procedure 
definitions without following executable statements. For more information 
on using ON_ERROR statements, see Section 3.8.4.7. 


SIGNALED 

ERRORS 

TPU$_COMPILEFAIL 

ERROR 

Compilation aborted because of 
syntax errors. 


TPU$_ARGMISMATCH 

ERROR 

The data type of a parameter 
passed to the COMPILE built-in is 
unsupported. 


TPU$_TOOFEW 

ERROR 

Too few arguments. 


TPU$_TOOMANY 

ERROR 

Too many arguments. 


EXAMPLES 

Q dwn := COMPILE ("MOVE_VERTICAL (1)") 

This assignment statement associates the MOVE_VERTICAL (1) function 
with the variable dwn. You can use the variable dwn with the built-in 
procedure EXECUTE to move the editing point down one line. 
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§ user^program := COMPILE (main_buffer) 

This assignment statement compiles the contents of the main buffer. If 
the buffer contains executable statements, VAXTPU returns a program 
that stores these executable commands. If the buffer contains procedure 
definitions, VAXTPU compiles the procedures and lists them in the 
procedure definition table so that you can call them in one of the following 
ways: 

• Enter the name of the procedure after the appropriate prompt from 
the interface you are using. 

• Call the procedure from within other procedures. 
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CONVERT 




Given the coordinates of a point in one coordinate system, returns the 
corresponding coordinates for the point in the coordinate system you specify. 

FORMAT 

r DECW ROOT WINDOW ) 
CONVERT SCREEN 

1 window ) 

j CHARACTERS, \ 

\ COORDINATES, f 


from_x_integer, from_y_integer, 

( DECW ROOT WINDOW \ 

{ SCREEN ' 

1 window ) 

f CHARACTERS, \ 

[ COORDINATES, j 


to_x_integer, to_yJnteger) 


PARAMETERS 

DECW ROOT WINDOW 



Specifies the coordinate system to be that used by the root window of the 
screen on which VAXTPU is running. 

SCREEN 

Specifies the coordinate system to be that used by the DECwindows 
window associated with VAXTPU’s top-level widget. 

window 

Specifies the coordinate system to be that used by the VAXTPU window. 

CHARACTERS 

Specifies a system that measures screen distances in rows and columns, as 
a character-cell terminal does. In a character-cell-based system, the cell in 
the top row and the leftmost column has the coordinates (1,1). 

COORDINATES 

Specifies a DECwindows coordinate system in which coordinate units 
correspond to pixels. The pixel in the upper left corner has the coordinates 
( 0 , 0 ). 

from_x_integer 

from_y_mteger 

Integer values representing a point in the original coordinate system and 
units. 

to_x_mteger 

to_y_integer 

Variables of type integer representing a point in the specified coordinate 
system and units. Note that the previous contents of the parameters are 
deleted when VAXTPU places the resulting values in them. You must 
specify VAXTPU variables for the parameters to_x_integer and tojy_ 
integer. Passing a constant integer, string or keyword value causes an 
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error. (This requirement does not apply to the parameters from_x_integer 
and from_y_integer.) 


DESCRIPTION The converted coordinates are returned using the tojcjnteger and to 

integer parameters. Note that coordinate systems are distinguished both 
by units employed and where each places its origin. 


SIGNALED 

ERRORS 

TPU$_ARGMISMATCH 

ERROR 

The data type of the indicated 
parameter is not supported by 
CONVERT. 


TPU$_BADDELETE 

ERROR 

You are attempting to modify 
an integer, keyword, or string 
constant. 


TPU$JNVPARAM 

ERROR 

One of the parameters was 
specified with data of the wrong 
type. 


TPU$_TOOFEW 

ERROR 

Too few arguments passed to 
CONVERT. 


TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
CONVERT. 


TPU$_BADKEY 

WARNING 

You specified an invalid keyword 
as a parameter. 


TPU$_WINDNOTVIS 

WARNING 

CONVERT cannot operate on an 
invisible window. 


EXAMPLE 


PROCEDURE user_convert 

LOCAL source___x, 
source_y, 
dest_x, 
dest_y; 

source_x := 1; 
source_y := 1; 
dest_x := 0; 
dest_y := 0; 

CONVERT (CURRENT_WINDOW, COORDINATES, source__x, source__y, 
SCREEN, COORDINATES, dest_x, dest__y) ; 


ENDPROCEDURE; 


This example converts a point’s location from the current window’s 
coordinate system (with the origin in the upper left-hand comer of the 
window) to the VAXTPU screen’s coordinate system (with the origin in 
the upper left-hand comer of the VAXTPU screen). For more information 
about the difference between a VAXTPU window and the VAXTPU screen, 
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see Chapter 4. If the current window is not the top window, CONVERT 
changes the value of the ^-coordinate to reflect the difference in the 
VAXTPU screen’s coordinate system. For another example of a procedure 
using the CONVERT built-in, see Example B-1. 
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COPY_TEXT 

Makes a copy of the text you specify and places it in the current buffer. 

FORMAT 

( buffer ] 

Irange2 := I COPY_TEXT f | rarigel ^ 

[ string J 

PARAMETERS 

buffer 

The buffer containing the text you want to copy. 

rangel 

The range containing the text you want to copy. 

string 

A string, a variable name representing a string constant, or an expression 
that evaluates to a string, representing the text you want to copy. 

return value 

The range where the copied text has been placed. 


DESCRIPTION If the current buffer is in insert mode, the text you specify is inserted 

before the current position in the current buffer. If the current buffer is in 
overstrike mode, the text you specify replaces text starting at the current 
position and continuing for the length of the string, range, or buffer. 

Note: You cannot add a buffer or a range to itself. If you try to add 
a buffer to itself, VAXTPU issues an error message. If you try 
to insert a range into itself, part of the range is copied before 
VAXTPU signals an error. If you try to overstrike a range into 
itself, VAXTPU may or may not signal an error. 

Using COPY_TEXT may cause VAXTPU to insert padding spaces or blank 
lines in the buffer. COPY_TEXT causes the screen manager to place the 
editing point at the cursor position if the current buffer is mapped to a 
visible window. (For more information on the distinction between the 
cursor position and the editing point, see Chapter 6.) If the cursor is not 
located on a character (that is, if the cursor is before the beginning of a 
line, beyond the end of a line, in the middle of a tab, or below the end of 
the buffer), VAXTPU inserts padding spaces or blank lines into the buffer 
to fill the space between the cursor position and the nearest text. 
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SIGNALED 

ERRORS 

TPU$_NOCURRENTBUF 

TPU$_NOCOPYBUF 

WARNING 

WARNING 

You are not positioned in a buffer. 

Trying to copy a buffer to itself is 
not allowed. 


TPU$_NOCACHE 

ERROR 

There is not enough memory to 
allocate a new cache. 


TPU$_OVERLAPRANGE 

ERROR 

You tried to put the contents of a 
range into that same range instead 
of into another structure. 


TPU$_TOOFEW 

ERROR 

COPY_TEXT requires one 
argument. 


TPU$_TOOMANY 

ERROR 

COPY_TEXT accepts only one 
argument. 


TPU$_ARGMISMATCH 

ERROR 

The argument to COPY__TEXT 
must be a string, range, or buffer. 


TPU$_NOTMODIFIABLE 

ERROR 

You cannot copy text Into an 
unmodifiable buffer. 


TPU$_LlNETOOLONG 

WARNING 

The line exceeds VAXTPU’s 
maximum line length. 


TPU$_TRUNCATE 

WARNING 

Characters have been truncated 
because you tried to add text that 
would exceed the maximum line 
length. 


EXAMPLES 

D COPY_TEXT ("Perseus is near Andromeda") 

When the buffer is set to insert mode, this statement causes the string 
"Perseus is near Andromeda" to be placed just before the current position 
in the current buffer. 

g COPY_TEXT (ASCII (10)) 

When the buffer is set to overstrike mode, this statement causes the 
ASCII character for line feed to replace the current character in the 
current buffer. 

g PROCEDURE user_simple_insert 

IF BEGINNING_OF (paste_buffer) = END_OF (paste_buffer) 

THEN 

MESSAGE ("Nothing to INSERT"); 

ELSE 

COPY_TEXT (paste_buffer); 

ENDIF; 

ENDPROCEDURE; 

This procedure implements a simple INSERT HERE function. It assumes 
that there is a paste buffer and that this buffer contains the most recently 
deleted text. The procedure copies the text from that buffer into the 
current buffer. 
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CREATE ARRAY 



Creates an array. 

FORMAT 

[ array := ] 

CREATE_ARRAY [ (integerl [, integer2J) ] 

PARAMETERS 

integerl 

The number of integer-indexed elements to be created when the array 
is created. VAXTPU processes elements specified by this parameter 
more quickly than elements created dynamically. You can add integer- 
indexed elements dynamically, but they are not processed as quickly as 
predeclared, integer-indexed elements. 

integer2 

The first predeclared integer index of the array. The predeclared integer 
indexes of the array extend from this integer through to integer2 + integerl 
- 1. This parameter defaults to 1. 

return value 

The variable that is to contain the newly created array. 

DESCRIPTION 

This built-in creates an array. 

In VAXTPU, an array is a one-dimensional collection of data values that 
can be considered or manipulated as a unit. 

To create an array variable called bat, use the CREATE_ARRAY built-in 
as follows: 

bat := CREATE_ARRA.Y; 

VAXTPU arrays can have a static portion, a dynamic portion, or both. A 
static array or portion of an array contains predeclared, integer-indexed 
elements. These elements are allocated contiguous memory locations to 
support quick processing. To create an array with a static portion, specify 
the number of contiguous, integer-indexed elements when you create the 
array. You also have the option of specifying a beginning index number 
other than 1. For example, the following statement creates an array with 
100 predeclared integer-indexed elements starting at 15: 

bat := CREATE_ARRAY (100, 15); 

All static elements of a newly created array are initialized to the data type 
unspecified. 

A dynamic portion of an array contains elements indexed with expressions 
evaluating to any VAXTPU data type except unspecified, learn, pattern, or 
program. Dynamic array elements are d 5 mamically created and deleted as 
needed. To create a dynamic array element, assign a value to an element 
of an existing array. For example, the following statement creates a 
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dynamic element in the array bat indexed by the string "bar" and assigns 
the integer value 10 to the element: 

bat{"bar"} := 10; 

To create an array with both static and dynamic elements, first create 
the static portion of the array. Then use assignment statements to create 
as many dynamic elements as you wish. For example, the following code 
fragment creates an array stored in the variable small_array. The array 
has 15 static elements and one dynamic element. The first static element 
is given the value 10. The dynamic element is indexed by the string "fred" 
and contains the value 100. 

sma1l_a r ray := CREATE_ARRAY (15); 
small_array{1} := 10; 
small_array{"fred"} := 100; 

To delete a dynamic array element, assign to it the constant TPU$K_ 
UNSPECIFIED, which is of type unspecified. 

One array can contain elements indexed with several data types. For 
example, you can create an array containing elements indexed with 
integers, buffers, windows, markers, and strings. An array element can be 
of any data type. All array elements of a newly created array are of type 
unspecified. 

If the same array has been assigned to more than one variable, VAXTPU 
does not create multiple copies of the array. Instead, each variable points 
to the array that has been assigned to it. VAXTPU arrays are reference 
counted, meaning that each array has a counter keeping track of how 
many variables point to it. VAXTPU arrays are autodelete data types, 
meaning that when no variables point to an array, the array is deleted 
automatically. You can also delete an array explicitly using the DELETE 
built-in. For example, the following statement deletes the array bat: 

DELETE (bat); 

If you delete an array that still has variables pointing to it, the variables 
receive the data type unspecified after the deletion. 

If you modify an array pointed to by more than one variable, modifications 
made using one variable show up when another variable references the 
modified element. To duplicate an array, you must write a procedure 
creating a new array and copying the old array’s elements to the new 
array. 

To refer to an array element, use the array variable name followed by an 
index expression enclosed in braces or parentheses. For example, if bar 
were a variable of type marker, the following statement would assign the 
integer value 10 to the element indexed by bar: 

bat{bar} := 10; 

You can perform the same operations on array elements that you can on 
other V^TPU variables, with one exception—you cannot make partial 
pattern assignments to array elements. 

See Chapter 2 for additional information about arrays. 
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SIGNALED 

ERRORS 

TPU$_TOOMANY 

ERROR 

CREATE_ARRAY accepts no 
more than two arguments. 


TPU$_NEEDTOASSIGN 

ERROR 

CREATE_ARRAY must appear 
on the right-hand side of an 
assignment statement. 


TPU$JNVPARAM 

ERROR 

The arguments to CREATE^ 
ARRAY must be integers. 


TPU$_MINVALUE 

WARNING 

The first argument to CREATE_ 
ARRAY must be 1 or greater. 


TPU$_MAXVALUE 

WARNING 

The first argument to CREATE_ 
ARRAY must be no greater than 
65,535. 


TPU$_GETMEM 

ERROR 

VAXTPU could not create the 
array because VAXTPU did not 
have enough memory. 


EXAMPLES 

D arrayl := CREATE_ARRAY; 

This assignment statement above creates an array and assigns it to the 
variable arrayl. 

g array2 := CREATE_ARRAY( 10 ); 

This assignment statement also creates an array. This array has ten 
predeclared integer-indexed elements that can be processed quickly by 
VAXTPU. It can also be indexed by any other VAXTPU data type except 
pattern, program, learn, and unspecified. 

g arrays := CREATE_ARRAY( 11, -5 ); 

This assignment statement creates an array that can be indexed by the 
integers -5 through 5. It can also be indexed by any other VAXTPU data 
type other than patterns and learn sequences. 
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CREATE BUFFER 



Defines a new work space for editing text. You can create an empty buffer 
or you can associate an input file name with the buffer. CREATE_BUFFER 
optionally returns a buffer. 

FORMAT 

[buffer2 := ] CREATE_BUFFER (stringl lstring2 [,buffer1] H,strings]]) 

PARAMETERS 

stringl 

A string representing the name of the buffer you want to create. 

string2 

A string representing the file specification of an input file that is read into 
the buffer. 

bufferl 

The buffer that you want to use as a template for the buffer to be created. 
The information copied from the template buffer includes the following: 

• End-of-buffer text 

• Direction (FORWARD/REVERSE) 

• Text entry mode (INSERT/OVERSTRIKE) 

• Margins (right and left) 

• Margin action routines 

• Maximum number of lines 

• Write-on-exit status (NO_WRITE) 

• Modifiable status 

• Tab stops 

• Key map list 

VAXTPU does not copy the following attributes of the template buffer to 
the new buffer: 

• Buffer contents 

• Marks or ranges 

• Input file name 

• Mapping to windows 

• Cursor position 

• Editing point 

• Associated subprocesses 

• Buffer name 

• Permanent status, if that is an attribute of the template buffer 
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• System status, if that is an attribute of the template buffer 

Strings 

The name of the journal file to be used with the buffer. Note that VAXTPU 
does not copy the journal file name from the template buffer. Instead, 
CREATE_BUFFER uses strings as the new journal file name. If you do 
not specify strings, VAXTPU names the journal file using its journal file 
naming algorithm. For more information on the naming algorithm, see 
Section 1.7.1 in Chapter 1. 

EVE turns on buffer change journaling by default for each new buffer. 
However, the CREATE_BUFFER built-in does not automatically turn on 
journaling; if you are layering directly on VAXTPU, your application must 
use SET (JOURNALING) to turn journaling on. 

Journal files contain a record of all information being edited. 
Therefore, when editing files containing secure or confidential 
data, be sure to keep the journal files secure as well. 


The buffer created by CREATE.BUFFER. 


Although you do not have to assign the buffer that you create to a variable, 
you need to make a variable assignment if you want to refer to the buffer 
for future use. The buffer variable on the left-hand side of an assignment 
statement is the item that you must use when you specify a buffer as a 
parameter for other VAXTPU built-in procedures. For example, to move to 
a buffer for editing, enter the buffer variable after the built-in procedure 
POSITION: 

my_buffer_variable := CREATE_BUFFER ("my_buf fer_name’', •'my_file_name'’) ; 

POSITION (my_buffer_variable); 

The buffer name that you specify as the first parameter for the built-in 
procedure CREATE_BUFFER (for example, “my_buffer_name” is used by 
VAXTPU to identify the buffer on the status line). You can change the 
status line with the built-in procedure SET (STATUS_LINE). 

If you want to skip an optional parameter and specify a subsequent 
optional parameter, you must use a comma as a placeholder for the 
skipped parameter. 

You can create multiple buffers. Buffers can be empty or they can contain 
text. The current buffer is the buffer in which any VAXTPU commands 
that you execute take effect (unless you specify another buffer). Only one 
buffer can be the current buffer. See the built-in procedure CURRENT_ 
BUFFER for more information. 

A buffer is visible when it is associated with a window that is mapped to 
the screen. A buffer can be associated with multiple windows, in which 
case any edits that you make to the buffer are reflected in all of the 
windows in which the buffer is visible. To get a list of all the buffers in 
your editing context, use the built-in procedure SHOW (BUFFERS). 
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The following ke)nvords used with the built-in procedure SET allow you 

to establish attributes for buffers. The text describes the default for the 

attributes; 

• SET (EOB_TEXT, buffer, string) — The default end-of-buffer text is 
[EOB]. 

• SET (ERASE.UNMODIFIABLE, buffer, { }) — By default, 

unmodifiable records ceui be deleted from buffers by built-ins such as 
ERASE_LINE. 

• SET (FORWARD, buffer) — The default direction is forward. 

• SET (INSERT, buffer) — The default mode of text entry is insert. 

• SET (JOURNALING, buffer, | }) — By default, buffer change 

journaling is turned off. 

• SET (LEFT_MARGIN, buffer, integer) — The default left margin is 1 
(that is, the left margin is set in column 1). 

• SET (LEFT_MARGIN_ACTION, buffer, program_source) — By default, 
buffers do not have left margin action routines. 

• SET (MARGINS, buffer, integerl, integer2) — The default left margin 
is 1 and the default right margin is 80. 

• SET (MAX_LINES, buffer, integer) — The default maximum number 
of lines is 0 (in other words, this feature is turned off). 

• SET (MODIFIABLE, buffer, { }) — By default, a buffer can be 

modified. Using the OFF keyword makes a buffer unmodifiable. 

|) — Turns on or turns off the bit 

indicating that the specified buffer has been modified. 

SET (NO_WRITE, buffer |[,ke 5 rwordI) — By default, when you exit 
from VAXTPU, the buffer is written if it has been modified. 

SET (OUTPUT_FILE, buffer, string) — The default output file is the 
input file specification with the highest existing version number for 
that file plus 1. 

SET (OVERSTRIKE, buffer) — The default mode of text entry is 
insert. 

SET (PERMANENT, buffer) — By default, the buffer can be deleted. 

SET (RECORD_ATTRIBUTE, marker, range, buffer) 

SET (REVERSE, buffer) — The default direction is forward. 

SET (RIGHT_MARGIN, buffer, integer) — The default right margin is 
80. 

SET (RIGHT_MARGIN_ACTION, buffer, program_source) — By 
default, buffers do not have right margin action routines. 

SET (SYSTEM, buffer) — By default, the buffer is a user buffer. 


SET (MODIFIED, buffer, { ^ 

^ Or r 
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• SET (TAB.STOPS, buffer, | |) - The default tab stops are 

set every eight character positions. 

See the built-in procedure SET for more information on these keywords. 


SIGNALED 

ERRORS 

TPU$_DUPBUFNAME 

WARNING 

First argument to the CREATE^ 
BUFFER built-in must be a unique 
string. 


TPU$_TRUNCATE 

WARNING 

A record was truncated to the 
maximum record length. 


TPU$_TOOMANY 

ERROR 

The CREATE_BUFFER built- 




in takes a maximum of two 
arguments. 


TPU$_TOOFEW 

ERROR 

The CREATE_BUFFER built-in 




requires at least one argument. 


TPU$JNVPARAM 

ERROR 

The CREATE_BUFFER built-in 




accepts parameters of type string 
or buffer only. 


TPU$_GETMEM 

ERROR 

VAXTPU ran out of virtual memory 
trying to create the buffer. 


TPU$_OPENIN 

ERROR 

CREATE_BUFFER did not open 
the specified input file. 

EXAMPLES 




D nb := CREATE_BUFFER 

("new__buf fer", "login. 

,com") 



This statement creates a buffer called NEW_BUFFER and stores a pointer 
to the buffer in the variable nb. Use the variable nb when you want to 
specify this buffer as a parameter for VAXTPU built-in procedures. The 
file specification "LOGIN.COM" is the input file for NEW_BUFFER. 

g default_buffer := CREATE_BUFFER ("defaults"); 

SET (REVERSE, default_buffer); 

b := CREATE_BUFFER ("buffer", "", default_buffer); 

The first statement in this example creates a buffer called DEFAULTS 
and stores a pointer to the buffer in the variable defaultJbuffer. The 
second statement sets the direction of default_buffer to reverse. The third 
statement creates a buffer called BUFFER and stores a pointer to the 
buffer in the variable b. This statement takes default information from 
default Jbuffer. Note that buffer b does not receive any text, marks, or 
ranges from the buffer default Jbuffer. 
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PROCEDURE user_help_buffer 

help_buf := CREATE_BUFFER("help_buf"); 

SET (EOB_TEXT, help_buf, "[End of HELP]"); 
SET (NO_WRITE, help_buf); 

SET (SYSTEM, help_buf); 

ENDPROCEDURE; 


This procedure creates the help buffer. 

Q bufl := CREATE_BUFFER ("Scratch",,,"Scratch_jl.jl"); 

This statement creates a buffer named Scratch and directs VAXTPU to 
name the associated buffer change journal file Scratchjl.jl. Note that 
you must use commas as placeholders for the two unspecified optional 
parameters. Note, too, that by default VAXTPU puts journal files in 
the directory defined by the logical name TPU$JOURNAL. By default, 
TPU$JOURNAL points to the same directory that SYS$SCRATCH points 
to. You can reassign TPU$JOURNAL to point to a different directory. 

g defaults_buffer := CREATE_BUFFER ("Defaults"); 

SET (EOB_TEXT, defaults_buffer, "[That's all, fol)cs!]"); 
user_buffer := CREATE_BUFFER ("Userl.txt", "", defaults_buffer); 

This code fragment creates a template buffer called Defaults, changes 
the end-of-buffer text for the template buffer, and then creates a user 
buffer. The user buffer is created with the same end-of-buffer text that the 
defaults buffer has. 
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CREATE KEY MAP 



Creates and names a key map. CREATE_KEY_MAP optionally returns a 
string that is the name of the key map created. 

FORMAT 

[string2 := ] CREATE_KEY_MAP (stringl) 

PARAMETER 

String 1 

A quoted string, or a variable name representing a string constant, that 
specifies the name of the key map you create. 

return value 

A string that is the name of the key map created. 

DESCRIPTION 

A key map is a set of key definitions. Key maps allow you to manipulate 
key definitions as a group. Key maps and their key definitions are saved 
in section files. The default key map for VAXTPU is TPU$KEY_MAP, 
contained in the default key map list TPU$KEY_MAP_LIST. See the 
description on key map lists. 

The EVE editor does not use the default key map, TPU$KEY_MAP. 

In EVE, the name of a key map is not the same as the variable that 
contains the key map. For example, the EVE variable EVE$X_USER_ 
KEYS contains the key map named EVE$USER_KEYS, which stores the 
user’s key definitions. EVE stores all its key maps in the default key map 
list, TPU$KEY_MAP_LIST. However, the default key map, TPU$KEY_ 
MAP, is removed from the default key map list by the standard EVE 
section file. 

When you create a key map, its keys are undefined. Each key map can 
hold definitions for all characters in the DEC Multinational Character Set, 
and all the keypad keys and the function keys, in both their shifted and 
unshifted forms. Each key map has its own name (a string). This name 
cannot be the same as that of either another key map or a key map list. 

SIGNALED 

ERRORS 

TPU$_DUPKEYMAP WARNING A key map with this name already 

exists. 

TPU$_TOOFEW ERROR Too few arguments passed to the 

CREATE_KEY_MAP built-in. 

TPU$_TOOMANY ERROR Too many arguments passed to 

the CREATE_KEY_MAP built-in. 

TPU$JNVPARAM ERROR Wrong type of data sent to the 

CREATE_KEY_MAP built-in. 
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EXAMPLE 


PROCEDURE init_sample_key_map 

sample_key_map := CREATE_KEY_MAP {"sample_key_map"); 

DEFINE_KEy ("EXIT", CTRL_Z_KEY, "Exit application", sample_key_map); 

DEFINE_KEY ("COPY_TEXT ('XYZZY')", CTRL_B_KEY, "Magic Word", sample_key_map); 

ENDPROCEDURE; 

This procedure creates a key map and defines two keys in the key map. 
The name of the key map is stored in the variable sample_key_map. 


7-64 









VAXTPU Built-In Procedures 

CREATE KEY MAP LIST 


CREATE KEY MAP LIST 



Creates and names a key map list, and also specifies the initial key maps 
in the key map list it creates. CREATE_KEY_MAP_LIST optionally returns a 
string that is the name of the key map list created. 

FORMAT 

[strings := ] 

CREATE_KEY_MAP_LIST (stringl, string2 

PARAMETERS 

String 1 

A quoted string, or a variable name representing a string constant, that 
specifies the name of the key map list that you create. 

string2 

Strings that specify the names of the initial key maps within the key map 
list you create. 

return value 

A string that is the name of the key map list created. 

DESCRIPTION 

A key map list is an ordered set of key maps. Key map lists allow you to 
change the procedures boimd to your keys. Tb find the definition of a given 
key, VAXTPU searches through the key maps in the specified or default 
key map list until VAXTPU either finds a definition for the key or reaches 
the end of the last key map in the list. 

VAXTPU provides the default key map list, TPU$KEY_MAP_LIST, 
containing the default key map, TPU$KEY_MAP. (See the description 
of the built-in procedure CREATE_KEY_MAP for more information on key 
maps.) 

The built-in procedure CREATE_KEY_MAP_LIST creates a new key map 
list, names the key map list, and specifies the initial key maps contained 
in the list. 

Key map lists store directions on what VAXTPU is to do when the user 
presses an undefined key associated with a printable character. By 
default, a key map list directs VAXTPU to insert undefined printable 
characters into the current buffer. To change the default, use the built-in 
procedure SET (SELFJNSERT). 

A newly created key map list is not bound to any buffer. To bind a key 
map list to a buffer, use the built-in procedure SET (KEY_MAP_LIST). 
When you use the POSITION built-in to select a current buffer, the key 
map list that is bound to the buffer is automatically activated. 

A newly created key map list has no procedure defined to be called when 
an undefined key is referenced. You can define such a procedure with the 
built-in procedure SET (UNDEFINED_KEY). The default is to display the 
message “key has no definition.” 
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Key map lists are saved in section files, along with any undefined key 
procedures and the SELFJNSERT settings. 


SIGNALED 

ERRORS 


TPU$_DUPKEYMAP 

WARNING 

The string argument is already 
defined as a key map. 

TPU$_DUPKEYMAPL1ST 

WARNING 

The string argument is already 
defined as a key map list. 

TPU$_NOKEYMAP 

WARNING 

The string argument is not a 
defined key map. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
CREATE_KEY_MAP_LIST buiit-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the CREATE_KEY_MAP_LIST 
built-in. 

TPU$_INVPARAM 

ERROR 

Wrong type of data sent to the 
CREATE_KEY_MAP_LIST built-in. 


EXAMPLE 

PROCEDURE init_help_key_map_list 

help_user_keys := CREATE_KEY_MAP ("help_user_keys"); 
help_keys := CREATE_KEY_MAP ("help_keys"); 

help_key_list := CREATE_KEY_MAP_LIST ("help_key_list", help_user_keys, 
help__keys) ; 

ENDPROCEDURE; 

This procedure creates two key maps and groups them into a key map list. 
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CREATE PROCESS 



Starts a subprocess and associates a buffer with it. You can optionally specify 
an initial command to send to the subprocess. CREATE_PROCESS returns a 
process. 

FORMAT 

process := CREATE_PROCESS (buffer [.string]) 

PARAMETERS 

buffer 

The buffer in which VAXTPU stores output from the subprocess. 

String 

A quoted string, a variable name representing a string constant, or an 
expression that evaluates to a string, that represents the first command 
that you want to send to the subprocess. If you do not want to include the 
first command when you use the built-in procedure CREATE_PROCESS, 
see the built-in procedure SEND for a description of how to send the first 
or subsequent commands to a subprocess. 

return value 

The process created. 

DESCRIPTION 

You can create multiple subprocesses. When you exit from VAXTPU, any 
subprocesses you have created with CREATE_PROCESS are deleted. If 
you want to remove a subprocess before exiting, use the built-in procedure 
DELETE with the process as a parameter (DELETE (pi)), or set the 
variable to integer zero as follows: 

prod := 0 

CREATE_PROCESS creates a subprocess of a VAXTPU session and all of 
the output from the subprocess goes into a VAXTPU buffer. You cannot 
run a program or utility that takes over control of the screen from a 
process created with this built-in procedure. (See Chapter 2 for a list 
of subprocess restrictions.) You can, however, use the built-in procedure 
SPAWN to create a subprocess that suspends your VAXTPU process and 
places you directly at DCL level. You can then run programs such as FMS 
or PHONE that control the whole screen. 

SIGNALED 

ERRORS 

TPU$_DUPBUFNAME WARNING First argument must be a unique 

string. 

TPU$_CREATEFAIL WARNING Unable to activate the subprocess. 

TPU$__TOOFEW ERROR Too few arguments passed to the 

CREATE_PROCESS built-in. 
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TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the CREATE_PROCESS built-in. 

TPU$_NEEDTOASSIGN 

ERROR 

The CREATE_PROCESS built-in 
call must be on the right-hand side 
of an assignment statement. 

TPU$_1NVPARAM 

ERROR 

Wrong type of data sent to the 
CREATE_PROCESS built-in. 

TPU$_CAPTIVE 

WARNING 

Unable to create a subprocess in 
a captive account. 

TPU$_NOTMODIFIABLE 

WARNING 

Attempt to change unmodifiable 
buffer. You can only write the 
output of the subprocess to a 
modifiable buffer. 

TPU$_NOPROCESS 

WARNING 

No subprocess to interact with. 
The process was deleted between 
the time that it was created and 
when VAXTPU attempted to send 
information to it. 

TPU$_SENDFA1L 

WARNING 

Unable to send data to the 
subprocess. 

TPU$_DELETEFAIL 

WARNING 

Unable to terminate the 
subprocess. 


EXAMPLES 

D my_mail___process := CREATE_PROCESS (second_buffer, "mail") 

This assignment statement creates a subprocess and specifies SECOND_ 
BUFFER as the buffer in which the output from the subprocess is 
stored. It also sends the DCL MAIL command as the first command to 
be executed. 

§ ! Create a buffer to hold the output from the DCL commands 

! "SET NOON" and "DIRECTORY". 

PROCEDURE user_dcl_process 

dcl_buffer := CREATE_BUFFER ("dcl__buffer") ; 

MAP (main_window, dcl_buffer); 

my_dcl_process := CREATE_PROCESS (dcl_buffer, "SET NOON"); 

MESSAGE ("Creating DCL subprocess..."); 

SEND ("DIRECTORY", my_dcl_process); 

ENDPROCEDURE; 

This procedure creates a buffer to hold the output from the DCL 
commands executed by the subprocess. 
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CREATE RANGE 


Returns a range that includes two delimiters and all the characters between 
them, and sets the video attributes for displaying the characters when they 
are visible on the screen. A range delimiter can be a marker, the beginning or 
end of a line, or the beginning or end of a buffer. The beginning and ending 
delimiters do not have to be of the same type but must be in the same buffer. 


FORMAT 


range := CREATE_RANGE 


,( markerl 1 ( 
* \ keywordl J' \ 
I, keyword2 ]) 


marker2 

keywordl 


PARAMETERS 


markerl 

The marker indicating the point in the buffer where the range begins. 

marker2 

The marker indicating the point in the buffer where the range ends. 

keywordl 

A keyword indicating the point in the buffer where you want the range to 
begin or end. Table 7-1 shows the vahd ke 3 rwords and their me 2 uiings. 

Table 7-1 CREATE RANGE Keyword Parameters 


Keyword 

Meaning 

LINE_BEGIN 

The beginning of the current buffer’s current line. 

LINE_END 

The end of the current buffer’s current line. 

BUFFER_BEGIN 

Line 1, offset 0 in the current buffer. This is the first position 
where a character could be inserted, regardless of whether there 
is a character there. This is the same as the point referred to by 
BEGINNING_OF (CURRENT_BUFFER). 

BUFFER_END 

The last position in the buffer where a character could be inserted. 
This is the same as the point referred to by END OF (CURRENT 
BUFFER). 

keyword2 

The video attribute for the range: BLINK, BOLD, NONE, REVERSE, or 
UNDERLINE. If you omit the parameter, the default is NONE. 


return value 


The range created by CREATE_RANGE. 
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0 |g 0 Qp|pi'|Q|^ CREATE_RANGE establishes a range that is delimited by the markers 

you specify. You can create multiple ranges in a buffer. When you apply 
video attributes to a range, you can see the range if it is in a visible buffer. 
A range may overlap another range. 

If you clear the contents of a range with the built-in procedure ERASE, 
the range structure still exists. The range and its video attributes, if any, 
move to the next character or position beyond where the range ended 
before the range was erased. 

To remove the range structure, use the built-in procedure DELETE or set 
the variable to which the range is assigned to zero (rl := 0 ). 

In portions of a range that either are associated with nonprintable 
characters or are not associated with characters at all, VAXTPU does 
not display any of the video attributes of the range. However, if you insert 
new characters into portions of a range where the video attributes have 
not been displayed, the new characters do display the video attributes that 
apply to the range. 

CREATE_RANGE checks whether the markers you specify as parameters 
are free markers. A free marker is a marker not bound to a character. 
For more information on free markers, see the description of the MARK 
built-in. 

If a marker defining a range is a free marker, VAXTPU ties the range 
to the character or end-of-Une nearest to the free marker, to use as the 
range delimiter. Note that an end-of-line is not a character but is a point 
to which a marker can be boimd. 


SIGNALED 

ERRORS 


TPU$_NOTSAMEBUF 

WARNING 

First and second marker are in 
different buffers. 

TPU$_TOOFEW 

ERROR 

CREATE_RANGE requires three 
parameters. 

TPU$_TOOMANY 

ERROR 

CREATE_RANGE accepts no 
more than three parameters. 

TPU$_NEEDTOASSIGN 

ERROR 

CREATE_RANGE must appear 
on the right-hand side of an 
assignment statement. 

TPU$JNVPARAM 

ERROR 

One of your arguments to 
CREATE_RANGE is of the wrong 
type. 

TPU$_BADKEY 

WARNING 

You specified an illegal keyword. 


EXAMPLES 

Q my_range := CREATE_RANGE (start_mark, end_mark, BOLD) 

This assignment statement creates a range starting at start_mark and 
ending at endjnark. When this remge is visible on the screen, the 
characters in the range are bolded. 
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§ PROCEDURE user_erase_to_eob 

LOCAL start__of_range, 
here_to_eob; 

start_of_range ;= MARK (NONE); 

here_to__EOB := CREATE__RANGE (start_of_range, 

END_OF (CURRENT_BUFFER), 
NONE); 

ERASE (here_to_eob); 

ENDPROCEDURE; 


This procedure erases the text in the current buffer, starting at the editing 
point, and erasing text until the end of the buffer is reached. 

g the_range := CREATE_RANGE (BUFFER_BEGIN, mark2, REVERSE); 

This statement creates a range starting at the first point in the buffer 
where a character can be inserted and ending at the point marked by 
mark2. If the range is visible on the screen, the characters in it are 
highlighted with the reverse video attribute. 







VAXTPU Built-In Procedures 

CREATE WIDGET 


CREATE_WIDGET 

Creates a widget instance. The CREATE_WIDGET built-in has two variants 
with separate syntaxes. One variant creates and returns a widget using the 
intrinsics or a XUI Toolkit low-level creation routine. The other variant creates 
an entire hierarchy of widgets (as defined in an XUI Resource Manager 
database) and returns the topmost widget. 


FORMAT 


widget := CREATE_WIDGET 


(widget_class, widget_name, 
( parent_widget \ 

\ SCREEN J 
buffer 

learn_sequence 
I ^ program 
range 
string 
[, closure 

I widgetargs... ]]J) 


DESCRIPTION Creates the widget instance you specify, using the intrinsics or an XUI 

Toolkit low-level creation routine. Although it has been created, the 
returned widget is not managed and therefore not visible. The application 
must call the MANAGE_WIDGET built-in to make the widget visible. 


FORMAT 


widget := CREATE_WIDGET (resource_manager_name, hierarchyjd, 

f parent_widget I 
I SCREEN i 
' buffer 

learnjsequence 
[, ^ program 
range 
. string 
I closure 

IT, widgetargs... n ]) 


DESCRIPTION Creates and returns an entire hierarchy of widgets (as defined in an XUI 

Resource Manager database) and returns the topmost widget. All children 
of the returned widget are also created and managed. The topmost widget 
is not managed, so none of the widgets created is visible. 

If you specify one or more callback arguments in your User Interface 
Language (UIL) file, specify either the routine TPU$WIDGET_INTEGER_ 
CALLBACK or the routine TPU$WIDGET_STRING_CALLBACK. 

For more information about specifying callbacks, see Chapter 4. For 
more information about UIL files, see the VMS DECwindows Guide to 
Application Programming. 
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When you use CREATE_WIDGET to create a widget or hierarchy of 
widgets organized by the XUI Resource Manager, CREATE WIDGET uses 
the XUI Toolkit routine FETCH WIDGET. 

PARAMETERS 

widget_class 

The integer returned by DEFINE_WIDGET_CLASS that specifies the 
class of widget to be created. 

widget_name 

A string that is the name to be given to the widget. 

parent_widget 

The widget that is to be the parent of the newly created widget. 

SCREEN 

A keyword indicating that the newly created widget is to be the child of 
VAXTPU’s main window widget. 

buffer 

The buffer containing the interface callback routine. This code is executed 
when the widget performs a callback to VAXTPU; all widgets created with 
a single CREATE_WIDGET call use the same caUback code. If you do not 
specify this parameter, VAXTPU does not execute any callback code when 
the widget performs a callback to VAXTPU. 

Iearn_sequence 

The learn sequence that is the interface callback routine. This is executed 
when the widget performs a callback to VAXTPU; all widgets created with 
a single CREATE_WIDGET call use the same callback code. If you do not 
specify this parameter, VAXTPU does not execute any callback code when 
the widget performs a callback to VAXTPU. 

program 

The program that is the interface callback routine. This is executed when 
the widget performs a callback to VAXTPU; all widgets created with a 
single CREATE_WIDGET call use the same callback code. If you do not 
specify this parameter, VAXTPU does not execute any callback code when 
the widget performs a callback to VAXTPU. 

range 

The range containing the interface callback routine. This is executed when 
the widget performs a callback to VAXTPU; all widgets created with a 
single CREATE_WIDGET caU use the same callback code. If you do not 
specify this parameter, VAXTPU does not execute any callback code when 
the widget performs a callback to VAXTPU. 

String 

The string containing the interface callback routine. This is executed 
when the widget performs a callback to VAXTPU; all widgets created with 
a single CREATE_WIDGET call use the same callback code. If you do not 
specify this parameter, VAXTPU does not execute any callback code when 
the widget performs a callback to VAXTPU. 
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return value 


DESCRIPTION 


closure 

A string or integer. VAXTPU passes the value to the apphcation when the 
widget performs a callback to VAXTPU. For more information about using 
closures, see Chapter 4. 

If you do not specify this parameter, VAXTPU passes the closure value (if 
any) given to the widget in the UIL file defining the widget. If you specify 
the closure value with CREATE_WIDGET instead of in the UIL file, all 
widgets created with the same CREATE_WIDGET call have the same 
closure value. 

widget_args 

One or more pairs of resource names and resource values. You can 
specify a pair in an array or as a pair of separate parameters. If you 
use an array, you index the array with a string that is the name of the 
resource you want to set. Note that resource names are case-sensitive. 
The corresponding array element contains the value you want to assign to 
that resource. The array can contain any number of elements. If you use 
a pair of separate parameters, use the following format: 

resource_name_string, resource_value 

Arrays and string/value pairs may be interspersed. Each array index 
and its corresponding element value, or each string and its corresponding 
value, must be valid widget arguments for the class of widget you are 
creating. 

resource_manager_name 

A case-sensitive string that is the name assigned to the widget in the UIL 
file defining the widget. 

hierarchyjd 

The hierarchy identifier returned by the SET (DRM_HIERARCHY) built- 
in. This identifier is passed to the XUI Resource Manager, which uses the 
identifier to find the resource name in the database. 


The newly created widget instance. 


The case of a widget’s name in the User Interface Definition (UID) file 
must match the case of the widget’s name that you specify as a parameter 
to CREATE_WIDGET. If you specify case sensitive widget names in 
your UIL file, you must use the same widget name case with CREATE^ 
WIDGET as you used in the UIL file. If you specify case insensitive widget 
names in your UIL file, the UIL compiler translates all widget names to 
uppercase, so in this instance you must use uppercase widget names with 
CREATE_WIDGET. The example in the following subsection specifies case 
insensitive widget names in the UIL file and specifies an uppercase name 
for the widget with the CREATE_WIDGET built-in. 
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SIGNALED 

ERRORS 


TPU$_BADKEY 

WARNING 

You specified an invalid keyword 
as a parameter. 

TPU$_UNDWIDCLA 

WARNING 

You have specified a widget 
class Integer that is not known to 
VAXTPU. 

TPU$JNVPARAM 

ERROR 

One of the parameters was 
specified with data of the wrong 
type. 

TPU$_NEEDTOASSIGN 

ERROR 

CREATE_WIDGET must return a 
value. 

TPU$_REQUIRESDECW 

ERROR 

You can use CREATE_WIDGET 
only If you are using DECwindows 
VAXTPU. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to 
CREATE_WIDGET. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
CREATE_WIDGET. 

TPU$_WIDMISMATCH 

ERROR 

You have specified a widget whose 
class is not supported. 

TPU$_ARGMISMATCH 

ERROR 

A widget argument was not an 
array or a string/value pair. 

TPU$_COMPILEFAIL 

WARNING 

Compilation of the widget interface 
callback routine failed due to 
syntax errors. 

TPU$_NONAMES 

WARNING 

A widget argument is not 
supported by the specified widget. 


EXAMPLES 

Q PROCEDURE eve_display__example 


LOCAL example_widget, 

example_widget_name , 


example_hierarchy; 


! Variable assigned to the created widget. 
! The name of the widget assigned 
! to this variable must be uppercase 
! if you specified case insensitive 
! widget names in the UIL file. 

! XUI Resource Manager 
! hierarchy for this example. 


ON_ERROR 

[OTHERWISE]: ! Traps errors. 

ENDON ERROR; 


! Set the widget hierarchy. The default file spec is "SYS$LIBRARY: .UID" 

example_hierarchy := SET (DRM__HIERARCHY, "mynode$duaO:[smith]example"); 

! The VAXTPU CREATE_WIDGET built-in needs the name of the widget 
! defined in the UIL file. 


example_widget_name := "EXAMPLE___BOX"; ! The widget EXAMPLE__BOX is 

! defined in the file EXAMPLE.UIL. 

! Create the widget if it has not already been created. 
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IF GET_INFO (example_widget, "type") <> WIDGET 
THEN 

example_widget : = CREATE_WIDGET (example_widget_name, example_hierarchy, 

SCREEN, eve $ kt_ca1Iback_routine); 

! EVE defines eve$callback_dispatch to be EVE's callback routine. 

! You do not need to define it again if you are extending EVE. 

ENDIF; 

! Map "example widget" to the screen using MANAGE_WIDGET. 

MANAGE_WIDGET (example_widget); 

RETURN (TRUE); 

ENDPROCEDURE; 

This procedure, evejiisplay_eocample, creates a modal dialog box widget 
and maps the widget to the VAXTPU screen. 

The procedure shows how to use the variant of CREATE_WIDGET that 
returns an entire widget hierarchy. To create a widget or widget hierarchy 
using this variant, you must have available the compiled form of a User 
Interface Language (UIL) file specifying the characteristics of the widgets 
you want to create. Digital recommends that you use one or more UIL files 
and the corresponding variant of CREATE__WIDGET whenever possible, 
because UIL is more efficient and because UIL files make it easier to 
translate your application into other languages. For more information 
about compiling and using UIL files, see the VMS DECwindows Guide to 
Application Programming, 

MODULE example 
VERSION = 'VOO-000' 

! This is a sample UIL file that creates a message box containing 
! the message "Hello World". 

NAMES = case___insensitive 
VALUE 

example_message : 'Hello World'; 

OBJECT 

example_box : message_box { 
arguments { 

default_position = true; ! puts box in center work area 

ok_label = example__button_label; 
label__label = example__message; 

}; 

}; 

END MODULE; 


This example shows a sample UIL file describing the modal dialog box 
called examplejbox. The UIL file specifies where the widget appears on 
the screen, what label appears on the box’s button, and what message the 
widget displays. 

For an example showing how to use the variant of CREATE_WIDGET that 
calls the XUI Toolkit low-level creation routine, see Example B-2. 
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CREATE WINDOW 



Defines a screen area called a window. You must specify the screen line 
number at which the window starts, the length of the window, and whether the 
status line is to be displayed. CREATE_WINDOW optionally returns the newly 
created window. 

FORMAT 

[window := ] 

CREATE WINDOW (integerl, integer2, 

1 OFF V 

PARAMETERS 

integerl 

The screen line number at which the window starts. 

mteger2 

The number of rows in the window. 

ON 

A kejword directing VAXTPU to display a status line in the new window. 
The status line occupies the last row of a window. By default, the status 
line is displayed in reverse video and contains the following information 
about the buffer that is currently mapped to the window: 

• The name of the buffer that is associated with the window 

• The name of the file that is associated with the buffer, if one exists 

See SET (STATUS_LINE) for information on changing the video attributes 
of the status line and/or the information displayed on the status line. 

OFF 

Suppresses the display of the status hne. 

return value 

The window created by CREATE_WINDOW. 

DESCRIPTION 

CREATE_WINDOW optionally returns the new window. If you want to 
use the window that you create as a parameter for any other built-in 
procedure, then you should specify a variable into which the window is 
returned. 

You can create multiple windows on the screen, but only one window can 
be the current window. The cursor is positioned in the current window. 

The current window and the current buffer are not necessarily the same. 

To make a window visible, you must associate a buffer with the window 
and map the window to the screen. The following command maps main_ 
window to the screen: 

MAP (main_window, main_buffer) 
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See the built-in procedure MAP for further information. 

The following ke5Words used with the built-in procedure SET allow you 
to establish attributes for windows. This list shows the defaults for the 
attributes; 

• SET (PAD, window, keyword) — By default, there is no blank padding 
on the right. 

• SET (SCROLL_BAR) — By default, VAXTPU does not create 
vertical and horizontal scroll bars for a window in the DECwindows 
environment. 

• SET (SCROLL_BAR_AUTO_THUMB) — By default, VAXTPU controls 
the slider in any scroll bars in a window. 

• SET (SCROLLING, window, keyword, integerl, integer2, integers) — 
The default cursor limit for scrolling at the top of the screen is the first 
line of the window; the default cursor limit for scrolling at the bottom 
of the screen is the bottom line of the window. If the terminal type 
you are using does not allow you to set scrolling regions, the window is 
repainted. 

• SET (STATUS_LINE, window, keyword, string) — The status line 
may be ON or OFF according to the keyword specified for the built-in 
procedure CREATE_WINDOW. See the preceding description of the 
keyword ON for information about the default attributes of a status 
line. 

• SET (TEXT, window, keyword) — By default, the text is set to 
BLANK_TABS (tabs are displayed as blank spaces). 

• SET (VIDEO, window, keyword) — There are no video attributes by 
default. 

• SET (WIDTH, window, integer) — By default, the width is the same as 
the physical width of the terminal screen when the window is created. 

See the built-in procedure SET for more information on these keywords. 

Using the SHIFT built-in, you can display text that lies to the right of the 
window’s right edge in an unshifted window. For information on using 
SHIFT, see the description of the built-in in this chapter. 


SIGNALED 

ERRORS 


TPU$_TOOFEW 


ERROR The CREATE_WINDOW built-in 

requires exactly three parameters. 

ERROR The CREATE_WINDOW built-in 

accepts exactly three parameters. 

ERROR The keyword must be either ON or 

OFF. 


TPU$_TOOMANY 


TPU$_BADKEY 
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TPU$JNVPARAM 

TPU$_BADWINDLEN 

TPU$_BADFIRSTLINE 


ERROR One or more of the specified 

parameters have the wrong type. 

WARNING Invalid window length. 

WARNING Invalid first line for window. 


EXAMPLES 

D new_window := CREATE_WINDOW (11, 10, ON) 

This assignment statement creates a window that starts at screen line 11 
and is 10 rows long, and assigns it to the variable newjLuindow. A status 
line is displayed as the last line of the window. To make this window 
visible, you must associate an existing buffer with it and map the window 
to the screen with the following command: 

MAP (new__window, buffer__variable) 

§ PROCEDURE user_make_window 

new_window := CREATE_WINDOW(1, 21, OFF); 

SET (TEXT, new_window, GRAPHIC_TABS); 
new_buffer := CREATE__BUFFER ("user_buffer_name"); 

SET (NO__WRITE, new_buffer) ; 

MAP (new__window, new_buf fer) ; 

ENDPROCEDURE; 

This procedure creates a window called newjuuindow that starts at screen 
line 1 and is 21 lines long. No status line is displayed. Tabs are displayed 
as special graphic characters. The buffer newjbuffer^ which is set to NO_ 
WRITE, is associated with the window and the window is mapped to the 
screen. 
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CURRENT_BUFFER 

Returns the buffer in which you are currentiy positioned. 


FORMAT 

buffer := CURRENT_BUFFER 


PARAMETERS 

None. 


return value 

The buffer in which you are currently positioned. 

• 

DESCRIPTION 

The current buffer is the work space in which any VAXTPU statements 
you execute take effect. The editing point is in the current buffer. Note 
that the editing point is not necessarily the same as the cursor position. 


SIGNALED 

ERRORS 

TPU$_TOOMANY ERROR CURRENT_BUFFER takes no 

parameters. 

TPU$_NEEDTOASSIGN ERROR The CURRENT_BUFFER built-in 

must be on the right-hand side of 
an assignment statement. 

TPU$_NOCURRENTBUF WARNING You are not positioned in a buffer. 

• 


EXAMPLES 

Q my___cur_buf 


CURRENT BUFFER 


This assignment statement stores a pointer to the current buffer in the 
variable my_curj)uf. 


SHOW (CURRENT_BUFFER) 

This statement returns the buffer in which you are currently positioned 
and uses that buffer as the parameter for the built-in procedure SHOW. 


PROCEDURE user_toggle_direction 

IF CURRENT__DIRECTION = FORWARD 
THEN 

SET (REVERSE, CURRENT__BUFFER) ; 

ELSE 

SET (FORWARD, CURRENT_BUFFER); 
ENDIF; 

ENDPROCEDURE; 


This procedure reverses the direction of the current buffer. 
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CURRENT CHARACTER 



Returns the character at the editing point in the current buffer. 

FORMAT 

string := CURRENT_CHARACTER 

PARAMETERS 

None. 

return value 

A string consisting of the character at the editing point in the current 
buffer. 

DESCRIPTION 

The editing point is the character position in the current buffer at which 
most editing operations are carried out. Each buffer maintains its own 
editing point, but only the editing point in the current buffer is the active 
editing point. An editing point, which always refers to a character position 
in a buffer, is not necessarily the same as the cursor position, which always 
refers to a location in a window. For more information on the distinction 
between the editing point and the cursor position, see Chapter 6. 

If the editing point is at the end of a line, CURRENT_CHARACTER 
returns a null string. If the editing point is at the end of a buffer, 
CURRENT_CHARACTER returns a null string and also signals a 
warning. 

Using CURRENT_CHARACTER may cause VAXTPU to insert padding 
spaces or blank lines in the buffer. CURRENT_CHARACTER causes the 
screen manager to place the editing point at the cursor position if the 
current buffer is mapped to a visible window. (For more information on 
the distinction between the cursor position and the editing point, see 
Chapter 6.) If the cursor is not located on a character (that is, if the cursor 
is before the beginning of a line, beyond the end of a line, in the middle of 
a tab, or below the end of the buffer), VAXTPU inserts padding spaces or 
blank lines into the buffer to fill the space between the cursor position and 
the nearest text. 

SIGNALED 

ERRORS 

TPU$_TOOMANY ERROR CURRENT_CHARACTER takes 

no parameters. 

TPU$_NEEDTOASS!GN ERROR The CURRENT_CHARACTER 

built-in must be on the right-hand 
side of an assignment statement. 

TPU$_NOCURRENTBUF WARNING You are not positioned in a buffer. 

TPU$_NOEOBSTR WARNING You are positioned at the EOB 

(end-of-buffer) mark. 
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EXAMPLES 

Q my_cur_char := CURRENT_CHARACTER 

This assignment statement stores the string that represents the editing 
point in the variable my_cur_char. 

g MESSAGE (CURRENT__CHARACTER) 

This statement returns the string that represents the editing point and 
uses this string as the parameter for the built-in procedure MESSAGE. 

@ PROCEDURE user_display_current__character 

! This procedure returns the ASCII character in the editing point. 

ascii_char := CURRENT_CHARACTER; 

IF ascii__char <> "" 

THEN 

MESSAGE ("The current character is + ascii_char + 

ELSE 

MESSAGE ("There is no current character."); 

ENDIF; 

ENDPROCEDURE; 

This procedure writes the character that is at the current character 
position into the message area. 
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CURRENT COLUMN 



Returns an integer that is the current column number of the cursor position on 
the screen. 

FORMAT 

integer := CURRENT_COLUMN 

PARAMETERS 

None. 

return value 

An integer that is the column number of the current cursor position on the 
screen. 

DESCRIPTION 

The current column is the column at which the cursor is positioned on 
the screen. The column numbers range from 1 on the extreme left of the 
screen to the maximum value allowed for the terminal type you are using 
on the extreme right of the screen. 

The value returned by the built-in procedure CURRENT_COLUMN 
and the value returned by GETJNFO (SCREEN, “current_column”) are 
equivalent. 

When used in a procedure, CURRENT_COLUMN does not necessarily 
return the position where the cursor has been placed by other statements 
in the procedure. VAXTPU generally does not update the screen until all 
statements in a procedure are executed. If you want the cursor position 
to reflect the actual editing location, put an UPDATE statement in your 
procedure immediately before any statements containing CURRENT 
COLUMN, as follows: 

UPDATE (CURRENT^WINDOW); 

If you do not want to update a window to get the current value for 
CURRENT.COLUMN, you can use the built-in GETJNFO (buffer, 
variable, “offset.column”). This built-in returns the column number that 
the current offset in the buffer would have if it were mapped to a window, 
and if you were to force a screen update. Note, however, that this built-in 
returns an accurate value only if both of the following conditions are true: 

• You are using bound cursor movement (MOVE.VERTICAL, 
MOVE.HORIZONTAL) or other built-in procedures that cause cursor 
movement because of character movement within a buffer. 

• The window is not shifted. 

The built-in GETJNFO (window.variable, “current.column”) does not 
necessarily return the column number that the cursor would occupy if you 
caused an explicit screen update. 


7-83 













VAXTPU Built-In Procedures 

CURRENT COLUMN 


If a window is shifted, CURRENT_COLUMN still returns the current 
column number of the cursor on the screen. However, the value returned 
by X := GETJNFO (buffer, "off*set__column") includes the number of 
columns by which the window is shifted. For example, if a window is 
shifted to the left by 8 columns, CURRENT_COLUMN returns the value 
1, while X := GETJNFO (buffer, "offset^column”) returns the value 9. 


SIGNALED 

TPU$_TOOMANY 

ERROR 

CURRENT_COLUMN takes no 

ERRORS 



parameters. 


TPU$_NEEDTOASSIGN 

ERROR 

The CURRENT_COLUMN built-in 


TPU$_NOCURRENTBUF 

WARNING 

must be on the right-hand side of 
an assignment statement. 

You are not positioned in a buffer. 


EXAMPLES 

Q my_cur_col := CURRENT_COLUMN 

This assignment statement stores the column position of the cursor in the 
variable my_cur_coL 

g MESSAGE (STR (CURRENT_COLUMN)) 

This statement combines three VAXTPU built-in procedures. CURRENT_ 
COLUMN returns the integer that is the current column position, STR 
converts the integer to a string, and MESSAGE writes this string to the 
message buffer. 

@ PROCEDURE user_split_line 

LOCAL old__position, new__position/ 

SPLIT_LINE; 

IF (CURRENT_ROW = 1) AND (CURRENT__COLUMN = 1) 

THEN 

old___position := MARK (NONE) ; 

SCROLL (CURRENT_WINDOW, -1); 
new_position := MARK (NONE); 

IMake sure we scrolled before doing CURSOR__VERTICAL 
IF new_position <> old_position 
THEN 

CURSOR__VERTICAL (1)/ 

ENDIF; 

ENDIF; 

ENDPROCEDURE; 

This procedure splits a line at the editing point. If the editing point is row 
1, column 1, the procedure causes the screen to scroll. 
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CURRENT DIRECTION 



Returns a keyword (FORWARD or REVERSE) that indicates the current 
direction of the current buffer. See aiso the descriptions of the buiit-in 
procedures SET (FORWARD) and SET (REVERSE). 

FORMAT 

keyword := CURRENT_DIRECTION 


PARAMETERS None. 


return value 

A keyword (FORWARD or REVERSE) indicating the current direction of 
the current buffer. 

DESCRIPTION 

If the kejnword FORWARD is returned, the current direction is toward 
the end of the buffer. If the keyword REVERSE is returned, the current 
direction is toward the beginning of the buffer. 

SIGNALED 

ERRORS 

TPU$_TOOMANY ERROR CURRENT_DIRECTION takes no 

parameters. 

TPU$_NEEDTOASSIGN ERROR The CURRENT_DIRECTION built- 

in must be on the right-hand side 
of an assignment statement. 

TPU$_NOCURRENTBUF WARNING You are not positioned in a buffer. 


EXAMPLES 

D my_cur_dir := CURRENT__DIRECTION 

This assignment statement stores in the variable my_cur_dir the ke 3 nvord 
that indicates whether the current direction setting for the buffer is 
FORWARD or REVERSE. 

§ PROCEDURE user__show__direction 

IF CURRENT_DIRECTION = FORWARD 
THEN 

my_messagel := MESSAGE ("Forward”); 

ELSE 

my_message2 := MESSAGE ("Reverse"); 

ENDIF; 

ENDPROCEDURE; 

This procedure writes to the message buffer a message indicating the 
current direction of character movement in the buffer. 
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CURRENT LINE 



Returns a string that represents the current line. The current line is the line 
that contains the editing point. 

FORMAT 

string := CURRENT_UNE 

PARAMETERS 

None. 

return value 

A string representing the current line. 

DESCRIPTION 

If you are positioned on a line that has a length of 0, CURRENT_LINE 
returns a null string. If you are positioned at the end of the buffer, 
CURRENT_LINE returns a null string and also signals a warning. 

Using CURRENT_LINE may cause VAXTPU to insert padding spaces or 
blank lines in the buffer. CURRENT_LINE causes the screen manager 
to place the editing point at the cursor position if the current buffer is 
mapped to a visible window. (For more information on the distinction 
between the cursor position and the editing point, see Chapter 6.) If the 
cursor is not located on a character (that is, if the cursor is before the 
beginning of a line, beyond the end of a line, in the middle of a tab, or 
below the end of the buffer), VAXTPU inserts padding spaces or blank 
lines into the buffer to fill the space between the cursor position and the 
nearest text. 

SIGNALED 

ERRORS 

TPU$_TOOMANY ERROR CURRENT_LINE takes no 

parameters. 

TPU$_NEEDT0ASS1GN ERROR The CURRENT_LINE built-in must 

be on the right-hand side of an 
assignment statement. 

TPU$_NOCURRENTBUF WARNING You are not positioned in a buffer. 

TPU$_NOEOBSTR WARNING You are positioned at or beyond 

the EOB (end-of-buffer) mark. 


EXAMPLES 

D my_cur_lin := CURRENT_LINE 

This assignment statement stores in the variable my_cur_lin the string 
that represents the current line. The current line is the line in the current 
buffer that contains the editing point. 
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§ PROCEDURE user_runoff_line 

IF LENGTH (CURRENT_LINE) < 2 
THEN 

user_runoff_line := 0; 

ELSE 

IF CURRENT__CHARACTER <> 

THEN 

user__runoff_line := 0; 

ELSE 

MOVE_HORIZONTAL (1); 

IF INDEX 

("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!; 
CURRENT_CHARACTER) = 0 
THEN 

user__runoff_line := 0; 

ELSE 

user_runoff__line ;= 1; 

ENDIF; 

MOVE_HORIZONTAL (-1); 

ENDIF; 

ENDIF; 

ENDPROCEDURE; 

This procedure returns true if the current line has the format of a DSR 
command (starts with a period followed by an alphabetic character, a 
semicolon, or an exclamation point). If not, the procedure returns false. 
The procedure assumes that the cursor was at the beginning of the line, 
and moves it back to the beginning of the line when done. 
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CURRENT, 

OFFSET 

Returns an integer for the offset of the editing point within the current line. 

FORMAT 

integer := CURRENT_OFFSET 

PARAMETERS 

None. 

return value 

An integer that is the offset of the editing point within the current line. 


DESCRIPTION The current offset is the number of positions a character is located from 

the first character position in the current line (offset 0). In VAXTPU, the 
leftmost character position is offset 0, and this offset is increased by 1 
for each character position (including the TAB character) to the right. 
VAXTPU numbers columns starting with the leftmost position on the 
screen where a character could be placed, regardless of where the margin 
is. This leftmost position is numbered 1. 

Note: The current offset value is not the same as the position of the 

cursor on the screen. See the CURRENT_COLUMN built-in if you 
want to determine where the cursor is. For example, if you have 
a line with a left margin of 10 and if the cursor is on the first 
character in that line, then CUKRENT.OFFSET returns 0, while 
CURRENT^COLUMN returns 10. 

Using CURRENT_OFFSET may cause VAXTPU to insert padding 
spaces or blank lines in the buffer. CURRENT_OFFSET causes the 
screen manager to place the editing point at the cursor position if the 
current buffer is mapped to a visible window. (For more information on 
the distinction between the cursor position and the editing point, see 
Chapter 6.) If the cursor is not located on a character (that is, if the cursor 
is before the beginning of a line, beyond the end of a line, in the middle of 
a tab, or below the end of the buffer), VAXTPU inserts padding spaces or 
blank lines into the buffer to fill the space between the cursor position and 
the nearest text. 

If you are using an interface with free cursor motion, when you move 
beyond the end of a line CURRENT_OFFSET makes the current cursor 
position the new end-of-line. 

If the current offset equals the length of the current line, you are 
positioned at the end of the line. 
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SIGNALED 


ERRORS 

TPU$_TOOMANY 

ERROR 

CURRENT_OFFSET takes no 
parameters. 


TPU$_NEEDTOASSIGN 

ERROR 

The CURRENT_OFFSET built-in 




must be on the right-hand side of 
an assignment statement. 


TPU$_NOCURRENTBUF 

WARNING 

You are not positioned in a buffer. 

EXAMPLES 




Q my_cur_off 

:= CURRENT_OFFSET 




This assignment statement stores the integer that is the offset position of 
the current character in the variable my_curjoff. 

g PROCEDURE user_delete 

IF CURRENT_OFFSET = 0 

THEN 

APPEND_LINE; 

ELSE 

ERASE_CHARACTER (-1); 

ENDIF; 

ENDPROCEDURE; 

This procedure uses the built-in procedure CURRENT^OFFSET to 
determine whether the editing position is at the beginning of a line. (For 
more information on the difference between the editing position and the 
current cursor position, see Chapter 6.) If the position is at the beginning, 
the procedure appends the current line to the previous line; otherwise, it 
deletes the previous character. Compare this procedure with the procedure 
used as an example for the built-in procedure APPEND_LINE. 
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CURRENT_ROW 



Returns an integer that is the screen iine on which the cursor is iocated. 

FORMAT 

Integer := CURRENT_ROW 

PARAMETERS 

None. 

return value 

An integer representing the screen line on which the cursor is located. 

DESCRIPTION 

The current row is the screen line on which the cursor is located. The 
screen lines are numbered from 1 at the top of the screen to the maximum 
number of lines available on the terminal. You can get the value of 
the current row by using the built-in procedure GETJNFO (SCREEN, 
“current_row”). 

When used in a procedure, CURRENT_ROW does not necessarily return 
the position where the cursor has been placed by other statements in 
the procedure. The reason that the value returned by CURRENT_ROW 
may not be the current value is that VAXTPU generally does not update 
the screen until all statements in a procedure are executed. If you want 
the cursor position to reflect the actual editing location, put an UPDATE 
statement in your procedure immediately before any statements containing 
CURRENT_ROW, as follows: 

UPDATE (CURRENT_WINDOW); 

SIGNALED 

ERRORS 

TPU$_NEEDTOASSIGN ERROR The CURRENT^ROW built-in 

must be on the right-hand side of 
an assignment statement. 

TPU$_TOOMANY ERROR CURRENT^ROW takes no 

parameters. 


EXAMPLES 

D my__cur_row := CURRENT_ROW 

This assignment statement stores in the variable my_cur_row the integer 
that is the screen line number on which the cursor is located. 
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§ PROCEDURE user_go_up 

IF CURRENT_ROW = GET_INFO (CURRENT_WINDOW, "visible_top") 
THEN 

SCROLL (CURRENT_WINDOW, -1); 

ELSE 

CURSOR__VERTICAL (-1) ; 

ENDIF; 

ENDPROCEDURE; 


g PROCEDURE user_go_down 

IF CURRENT_ROW = GET_INFO (CURRENT_WINDOW, "visible_bottom”) 

THEN 

SCROLL (CURRENT_WINDOW, 1); 

ELSE 

CURSOR__VERTICAL (1) ; 

EndIF; 

ENDPROCEDURE; 

These procedures cause the cursor to move up or down the screen. Because 
CURSOR_VERTICAL crosses window boundaries, you must use the built- 
in procedure SCROLL to keep the cursor motion within a single window 
if you are using free cursor motion. (See CURSOR_HORIZONTAL and 
CURSOR__VERTICAL.) If the movement of the cursor would take it 
outside the window, the preceding procedures scroll text into the window 
to keep the cursor visible. You can bind these procedures to a key so that 
the cursor motion can be accomplished with a single keystroke. 
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CURRENT WINDOW 



Returns the window in which the cursor is visible. 

FORMAT 

window := CURRENT_WINDOW 

PARAMETERS 

None. 

return value 

The window in which the cursor is visible. 

DESCRIPTION 

The current window is the window on which you have most recently 
performed one of the following operations: 

• Selection using the POSITION built-in 

• Mapping to the screen using the MAP built-in 

• Adjustment using the ADJUST_WINDOW built-in 

The current window contains the cursor at the screen coordinates current_ 
row and current ^column. The current buffer is not necessarily associated 
with the current window. 

SIGNALED 

ERRORS 

TPU$_TOOMANY ERROR CURRENT_WINDOW takes no 

parameters. 

TPU$_NEEDTOASSIGN ERROR The CURRENT_WINDOW built-in 

must be on the right-hand side of 
an assignment statement. 

TPU$_WINDNOTMAPPED WARNING No windows are mapped to the 

screen. 


EXAMPLES 

n my_cur_win := CURRENT_WINDOW 

This assignment statement stores the window that holds the cursor in the 
variable my_cur_win. 
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§ PROCEDURE user_next_screen 
LOCAL how_much__scroll; 

how_much_scroll := GET_INFO (CURRENT__WINDOW, "visible_length”); 

SCROLL (CURRENT_WINDOW, how__much__scroll) ; 

ENDPROCEDURE; 

This procedure determines the length of the current window and then uses 
that value as a parameter for the built-in procedure SCROLL. 
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CURSOR HORIZONTAL 



Moves the cursor position across the screen and optionaiiy returns the cursor 
movement status. 

FORMAT 

[ integerZ :=I CURSOR_HORIZONTAL (integerl) 

PARAMETER 

integerl 

The signed plus or minus integer value that specifies the number of screen 
columns to move the cursor position. A positive value directs VAXTPU to 
move the cursor to the right; a negative value directs VAXTPU to move 
the cursor to the left. The value 0 causes VAXTPU merely to synchronize 
the active editing point with the cursor position. 

return value 

An integer representing the number of columns the cursor moved. If 
VAXTPU cannot move the cursor as msmy columns as specified by integerl, 
VAXTPU moves the cursor as many columns as possible. VAXTPU allows 
the return value to be negative. This notation is reserved for future 
versions of VAXTPU. A negative return value does not denote that the 
cursor moved to the left. Rather, the integer shows the number of spaces 
that the cursor moved right or left. If the cursor did not move, integer2 
has the value 0. If the CURSOR_HORIZONTAL built-in produces an 
error, the value of integer2 is indeterminate. 

DESCRIPTION 

The CURSOR__HORIZONTAL built-in procedure can be used to provide 
free cursor movement in a horizontal direction. Free cursor movement 
means that the cursor is not tied to text, but can move across all available 
columns in a screen line. 

If you move before the beginning of a line, after the end of a line, in the 
middle of a tab, or beyond the end-of-file mark, other built-ins may cause 
padding lines or spaces to be added to the buffer. 

If you use the CURSOR_HORIZONTAL built-in within a procedure, screen 
updating occurs as follows: 

• When you execute a built-in that modifies the buffer or the editing 
point before you issue the call to CURSOR_HORIZONTAL, the screen 
is updated before CURSOR_HORIZONTAL is executed. This action 
ensures that the horizontal movement of the cursor starts at the 
correct character position. 

• Otherwise, the screen manager does not update the screen until the 
procedure has finished executing and control is returned to the screen 
manager. 

CURSOR_HORIZONTAL does not move the cursor beyond the left or right 
edge of the window in which it is located. You cannot move the cursor 
outside the bounds of a window. 
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CURSOR_HORIZONTAL has no effect if you use any input device other 
than a video terminal supported by VAXTPU. 

SIGNALED 

ERRORS 

TPU$_TOOFEW ERROR CURSOR_HORIZONTAL requires 

one parameter. 

TPU$_TOOMANY ERROR CURSOR_HORIZONTAL accepts 

only one parameter. 

TPU$JNVPARAM ERROR One or more of the specified 

parameters have the wrong type. 


EXAMPLES 

D int_x := CURSOR_HORIZONTAL (1) 

This statement moves the cursor position one screen column to the right. 

§ PROCEDURE user_free_cursor_right 

move_right := CURSOR_HORIZONTAL (1); 

ENDPROCEDURE; 

§ PROCEDURE user_free_cursor_left 

move_left := CURSOR_HORIZONTAL (-1); 


ENDPROCEDURE; 

These procedures provide for free cursor motion to the right and to the 
left. These procedures can be bound to keys (for example, the arrow keys) 
so that the movement can be accomplished with a single keystroke. 
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CURSOR VERTICAL 



Moves the cursor position up or down the screen and optionaily returns the 
cursor movement status. 

FORMAT 

Ilnteger2 :=1 CURSOR_VERTICAL (integerl) 

PARAMETER 

integerl 

The signed integer value that specifies how many screen lines to move the 
cursor position. A positive value for integerl moves the cursor position 
down. A negative integer moves the cursor position up. 

return value 

An integer representing the number of rows that the cursor moved up or 
down. If VAXTPU could not move the cursor as many rows as specified by 
integerl, VAXTPU moves the cursor as many rows as possible. 

If CROSS_WINDOW_BOUNDS is set to ON, CURSOR.VERTICAL may 
position the cursor to another window. In this case, CURSORJVERTICAL 
returns the negative of the number of rows the cursor moved. A negative 
return value does not denote that the cursor moved upward. 

If the cursor did not move, integer2 has the value 0. If the CURSOR_ 
VERTICAL built-in produced an error, the value of integer2 is 
indeterminate. 

DESCRIPTION 

CURSOR_VERTICAL can be used to provide fi*ee cursor movement in a 
vertical direction. Free cursor movement means that the cursor is not tied 
to text, but that it can move up and down to all lines on the screen that 
can be edited, whether or not there is text at that column in the new line. 

The cursor does not move beyond the top or the bottom edges of the screen. 
However, CURSOR_VERTICAL can cross window boundaries, depending 
upon the current setting of the CROSS_WINDOW_BOUNDS fiag. See 
SET (CROSS_WINDOW_BOUNDS) for information on how to set this flag. 
(Use the POSITION built-in to move the cursor to a different window on 
the screen.) 

When CROSS_WINDOW_BOUNDS is set to ON, CURSOR.VERTICAL 
can move the cursor position to a new window. The new window in which 
the cursor is positioned becomes the current window. The column position 
of the cursor remains unchanged unless vertical movement would position 
the cursor outside the bounds of a window narrower than the previous 
window. In this instance, the cursor moves to the left until it is positioned 
within the right boundary of the narrower window. 

When CROSS_WINDOW_BOUNDS is set to OFF, CURSOR.VERTICAL 
does not move the cursor outside the current window. If the SET 
(SCROLLING) built-in has been used to set scrolling margins, CURSOR_ 
VERTICAL also attempts to keep the cursor within the scroll margins. 
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CURSOR_VERTICAL positions the cursor only in screen areas in which 
editing can occur. For example, CURSOR^VERTICAL does not position 
the cursor on the status line of a window, in the prompt area, or in an 
area of the screen that is not part of a window. The blank portion of a 
segmented window is not considered part of a window for this purpose. 

If you use CURSOR_VERTICAL within a procedure, screen updating 
occurs as follows: 

• When you execute a built-in that modifies the buffer or the current 
character position before you issue the call to CURSOR_VERTICAL, 
the screen is updated before CURSOR_yERTICAL is executed. This 
action ensures that the vertical movement of the cursor starts at the 
correct character position. 

• Otherwise, the screen manager does not update the screen until the 
procedure has finished executing and control is returned to the screen 
manager. 

CURSOR_VERTICAL has no effect if you use an input device other than a 
video terminal supported by VAXTPU. 


SIGNALED 

ERRORS 

TPU$_TOOFEW 

ERROR 

CURSOR_VERTICAL requires at 
least one parameter. 


TPU$_TOOMANY 

ERROR 

CURSOR^VERTICAL accepts at 
most one parameter. 


TPU$JNVPARAM 

ERROR 

You did not specify an integer as 
the parameter. 


EXAMPLES 

D int_y ;= CURSOR_VERTICAL (5) 

This statement moves the cursor position five lines toward the bottom of 
the screen. 

§ ! Free cursor motion procedures 

PROCEDURE user_free__cursor__up 

IF GET__INFO (CURRENT_WINDOW, "CURRENT_ROW") = 

GET__INFO (CURRENT_WINDOW, ”VISIBLE_TOP ”) 

THEN 

SCROLL (CURRENT_WINDOW, -1); 

ELSE 

left_y := CURSOR_VERTICAL (-1); 

ENDIF; 

ENDPROCEDURE; 
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PROCEDURE user__free_cursor_down 

IF GET_INFO (CURRENT_WINDOW, "CURRENT_ROW") = 

GET_INFO (CURRENT_WINDOW, "VISIBLE_BOTTOM") 

THEN 

SCROLL (CURRENT_WINDOW, 1); 

ELSE 

right_x := CURSOR_VERTICAL (1); 

ENDIF; 

ENDPROCEDURE; 

These procedures provide for free cursor motion up and down the screen. 
These procedures can be bound to keys (for example, the arrow keys) so 
that the movement can be accomplished with a single keystroke. 

These examples work regardless of the setting of CROSS_WINDOW_ 
BOUNDS, because the built-in procedure SCROLL keeps the cursor 
motion within a single window. 
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DEBUG LINE 



Returns the line number of the current breakpoint. 

FORMAT 

integer := DEBUG.LINE 

PARAMETERS 

None. 

return value 

An integer representing the line number of the current breakpoint. 

DESCRIPTION 

The DEBUG__LINE built-in procedure returns the line number of the 
current breakpoint. Use DEBUG_LINE when writing your own VAXTPU 
debugger. 

Digital recommends that you use the debugger provided in 
SYS$SHARE:TPU$DEBUG.TPU. 

SIGNALED 

ERROR 

TPU$_NEEDTOASSIGN ERROR The DEBUG_LINE built-in must 

appear on the right-hand side of 
an assignment statement. 


EXAMPLE 

the_line := GET_INFO (DEBUG, "line_number"); 


IF the line = 0 

THEN the line := 
ENDIF; 

= DEBUG_LINE; 

This code fragment first uses GETJNFO to request the line number of 
the breakpoint in the current procedure. If the line number is 0, meaning 
that the breakpoint is not in a procedure, the code uses DEBUG_LINE to 
determine the breakpoint’s line number relative to the buffer. 
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DEFINE KEY 



Associates executable VAXTPU code with a key or a combination of keys. 

FORMAT 

' buffer 
learn 

DEFINE_KEY (< program >, key-name 
range 

. stringl j 
f ,string2 [,strings] ]) 

PARAMETERS 

buffer 

A buffer that contains the VAXTPU statements to be associated with a 
key. 

learn 

A learn sequence that specifies the executable code associated with a key. 

program 

A program that contains the executable code to be associated with a key. 

range 

A range that contains the VAXTPU statements to be associated with a key. 

Stringl 

A string that specifies the VAXTPU statements to be associated with a key. 

key-name 

A VAXTPU key name for a key or a combination of keys. See Table 2-1 for 
a list of the VAXTPU key names for the VT300, VT200, and VTIOO series 
of keyboards. You can also display all the VAXTPU keywords with the 
built-in procedure SHOW (KEYWORDS). 

See the Description section of this built-in procedure for information on 
keys that you cannot define. 

To define a key for which there is no VAXTPU key name, use the built-in 
procedure KEY_NAME to create your own key name for the key. For 
example, KEY_NAME ("A", SHIFT_KEY) creates a key name for the 
combination of PFl, the default shift key for VAXTPU, and the keyboard 
character A. For more information, see the description of the built-in 
procedure KEY_NAME. 

string2 

An optional string associated with a key that you define. The string is 
treated as a comment that can be retrieved with the built-in procedure 
LOOKUP_KEY. You might want to use the comment if you are creating a 
help procedure for keys that you have defined. 
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DEFINE KEY 


Strings 

A key map or a key map list in which the key is to be defined. If a key 
map list is specified, the key is defined in the first key map in the key map 
list. If neither a key map nor a key map list is specified, the key is defined 
in the first key map in the key map list bound to the current buffer. See 
the descriptions of the built-in procedures CREATE_KEY_MAP, CREATE_ 
KEY_MAP_LIST, and SET (KEY_MAP_LIST) for more information on key 
maps and key map lists. 


The built-in procedure DEFINE_KEY compiles the first parameter if it is 
a string, buffer, or range. 

If you use DEFINE_KEY to change the definition of a key that was 
previously defined, VAXTPU does not save the previous definition. 

You can define all the keys on the VT300, VT200, and VTIOO keyboards 
and keypads with the following exceptions: 

• The COMPOSE CHARACTER key on VT300 and VT200 keyboards 

• The SHIFT keys 

There are some keys that you can define but that Digital strongly 
recommends you avoid defining. VAXTPU does not signal an error 
when you use them as keyword parameters. However, in some cases 
the definitions you assign to these key combinations are not executed 
unless you set your terminal in special ways at the DCL level: 

• CTRL/C, CTRL/O, CTRL/X, and F6 — To execute programs that 
you bind to these keys, you must first enter the DCL command SET 
TERMINAL/PASTHRU. 

• CTRL/T, CTRL/Y — To execute programs that you bind to these keys, 
you must first enter the DCL command SET TERMINAL/PASTHRU 
and/or the DCL command SET NOCONTROL. 

• CTRL/S, CTRL/Q — To execute programs that you bind to these keys, 
you must first enter the DCL command SET TERMINAL/NOTTSYNC. 

• The PFl key — This is the default shift key for the editor. You cannot 
define PFl unless you use the biult-in procedure SET (SHIFT_KEY, 
ke 3 word) to define a different key as the shift key for the editor. 

• The ESCAPE key 

• The keys FI through F5 

Digital recommends that you do not use the special terminal settings 
mentioned above. The settings may cause unpredictable results if you do 
not understand all the implications of changing the default settings. 

Whenever you extend EVE by writing a procedure that can be bound to 
a key, the procedure must return true and false as needed to indicate 
whether execution of the procedure completed successfully. EVE’s 
REPEAT command relies on this return value to determine whether to 
halt repetition of a command, a procedure bound to a key, or a learn 
sequence. 


7-101 








VAXTPU Built-In Procedures 

DEFINE KEY 


SIGNALED 

ERRORS 


TPU$_NOTDEFINABLE 

WARNING 

Second argument is not 
a valid reference to a 
key. 

TPU$_RECURLEARN 

WARNING 

This key definition was 
used as a part of a learn 
sequence. You cannot 
use it in this context. 

TPU$_NOKEYMAP 

WARNING 

Fourth argument is not 
a defined key map. 

TPU$_NOKEYMAPLIST 

WARNING 

Fourth argument is not 
a defined key map list. 

TPU$_KEYMAPNTFND 

WARNING 

The key map listed in 
the fourth argument is 
not found. 

TPU$_EMPTYKMLIST 

WARNING 

The key map list 
specified in the fourth 
argument contains no 
key maps. 

TPU$_TOOFEW 

ERROR 

Too few arguments 
passed to the DEFINE_ 
KEY built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments 
passed to the DEFINE__ 
KEY built-in. 

TPU$JNVPARAM 

ERROR 

Wrong type of data sent 
to the DEFINE_KEY 
built-in. 

TPU$_COMPILEFAIL 

WARNING 

Compilation aborted. 

TPU$_UNKKEYWORD 

ERROR 

An unknown keyword 
has been used as an 
argument. 

TPU$_BADKEY 

ERROR 

An unknown keyword 
has been used as an 
argument. 

TPU$_KEYSUPERSEDED 

INFORMATIONAL 

Key definition 
superseded. 


EXAMPLES 

Q DEFINE_KEy ("POSITION (main_window)", CTRL_B_KEY) 

T his statement associates the VAXTPU statement POSITION (main_ 
window) with the key combination CTRITB. Note that you must use 
quotation marks aroimd the VAXTPU statement. 
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DEFINE_KEY (inain_buffer, KEY_NAME (PF4, SHIFT_KEY), "mainbuf") 

This statement causes VAXTPU to compile the main buffer (containing 
V^TPU statements). If there are no errors in the compilation, VAXTPU 
binds the executable code to the combination of the editor’s shift key (PFl 
by default) and PF4 on the keypad. The final string in the statement 
“mainbuf” is a comment that is associated with the key combination. 

DEFINE_KEY ('COPY_TEXT ("Extendable")', KEY_NAME ("z", SHIFT KEY)) 

This statement causes VAXTPU to make a copy of the word “Extendable” 
at the current character location in the current buffer when you press 
the key combination PFl (VAXTPU’s default shift key) and z. Notice that 
the inner set of quotation marks must be of a different kind from the 
outer set in the first parameter. Also notice that you must place quotation 
marks aroimd the keyboard character that you use in combination with 
the editor’s shift key. 

PROCEDURE user_define_key 

def := READ_LINE ("Definition: ") ; 

key := READ__LINE ("Press key to define.",!); 

IF LENGTH (key) > 0 
THEN 

key := KEY_NAME (key) 

ELSE 

key := LAST__KEY; 

ENDIF; 

DEFINE_KEY (def,key); 

ENDPROCEDURE; 


This procedure prompts the user for the VAXTPU statements to be bound 
to the key that the user specifies. 

PROCEDURE user_change_mode 

! Toggle mode between insert and overstrike 

IF GET_INFO (CURRENT_BUFFER, "mode") = OVERSTRIKE 
THEN 

SET (INSERT, CURRENT_BUFFER); 

ELSE 

SET (OVERSTRIKE, CURRENT_BUFFER); 

ENDIF; 

ENDPROCEDURE; 

! The following statement binds this procedure to the 
! key combination CTRL/A. This emulates the VMS key binding 
! that toggles between insert and overstrike for text entry 
! in command line editing. 

,DEFINE_KEY ("user_change_mode", CTRL_A_KEY); 

This procedure changes the mode of text entry from insert to overstrike, or 
from overstrike to insert. 

DEFINE_KEY ('MESSAGE ("Hello VAXTPU user")', CTRL__A__KEY, "Greeting", "TPU$KEY MAP") 

This example defines a key in a key map. The DEFINE_KEY statement 
defines CTRL/A in the key map TPU$KEY_MAP such that VAXTPU 
displays the message -Hello VAXTPU user- when CTRL/A is pressed. 
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DEFINE_KEY ("POSITION (MESSAGE_WINDOW)", F20,"", "movement_map") 

This example uses a key map (“movement_map”) but does not include a 
comment in the optional third parameter. Note the null string after the 
keyword F20 in the second parameter. 
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DEFINE_WIDGET_CLASS 


DEFINE_WIDGET_CLASS 



Defines a widget class and optional creation routine for later use in creating 
widgets of that class using the DECwindows intrinsics or the XUI Toolkit 
low-level creation routines. 

FORMAT 

integer := DEFINE_WIDGET_CLASS (class_name 
[, creation_routine_name 
[, creation_routine_image_name J |j 

PARAMETERS 

class_name 

A string that is the name of a universal symbol pointing to the desired 
widget class record. A universal symbol is a symbol in a sharable image 
that can be referred to in an image other than the one in which the sjrmbol 
is defined. 

creation_routine_name 

A string that is the name of the low-level widget creation routine for this 
widget class. Specify the case of the string correctly. To determine the 
correct case of the string, consult the documentation for the widget whose 
class you are defining, liie current version of VAXTPU, which is bundled 
with the VMS operating system, ignores the case of the string. However, 
future versions of VAXTPU may treat the string as case sensitive. 

If you do not specify this parameter, VAXTPU uses the X Toolkit CREATE 
WIDGET routine to create the widget instead of using a low-level widget 
creation routine. The routine must have the same calling sequence as the 
XUI Toolkit low-level widget creation routines. 

In the current version of VAXTPU, you must specify the VMS binding of 
the creation routine name. 

creation_routine_image_name 

A string that is the name of the shareable image in which the class 
record can be found. If you specify a low-level creation routine, DEFINE_ 
WIDGET_CLASS also looks for the routine in the program image. If 
you do not specify an image, VAXTPU assumes the widget is defined in 
SYS$LIBRARY:DECW$DWTLIBSHR.EXE. 

return value 

An integer used by the CREATE_WIDGET built-in to identify the class of 
widget to be created. 

DESCRIPTION 

Returns a class integer, which you use to specify the class of a widget 
when you create it. 
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DEFINE_WIDGET_CLASS 


SIGNALED 

ERRORS 


EXAMPLE 


Defining a class that is already defined returns the existing class integer. 
Defining a new class also defines the widget creation routine as the 
second parameter, if specified, or the X toolkit CREATE_WIDGET routine. 
VAXTPU searches for a new class record in the third parameter, if 
specified, or in SYS$LIBRARY:DECW$DWTLIBSHR.EXE. 


TPU$_ARGMISMATCH 

ERROR 

The data type of the indicated 
parameter is not supported by 
DEFINE_WIDGET__CLASS. 

TPU$_NEEDTOASSIGN 

ERROR 

DEFINE_WIDGET_CLASS must 
return a value. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to 
DEFINE__WlDGET_CLASS. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
DEFINE_WIDGET__CLASS . 

TPU$_REQUlRESDECW 

ERROR 

You can use DEFINE_WIDGET_ 
CLASS only if you are using 
DECwindows VAXTPU. 

TPU$_SYSERROR 

ERROR 

Could not find class record or 
creation routine in shareable 
image. 


For a sample procedure using the DEFINE_WIDGET_CLASS built-in, see 
Example B-2. 
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DELETE 


DELETE 


Removes VAXTPU structures from your editing context. When you deiete a 
structure (for example, a range) all variables that refer to that structure are 
reset to unspecified. If the deleted structure had any associated resources, 
these resources are returned to the editor. When a buffer is deleted, the 
associated journal file (if any) is closed and deleted. 


FORMAT 


DELETE (i 


' array 
buffer 
integer 
keyword 
learn 
marker 
pattern 
process 
program 
range 
string 

unspecified 
widget 
. window 


PARAMETERS array 

The array you want to delete. The memory used by the array is freed for 
later use. If some other data structure, such as a pattern, is referenced 
only in the array, then that data structure is deleted when the array is 
deleted. 

buffer 

The buffer you want to delete. Any ranges or markers that point to this 
buffer, any subprocess that is associated with this buffer, the memory for 
the buffer control structure, the pages for storing text, and the memory 
for ranges and markers associated with the buffer are deleted also. If 
the buffer is associated with a window that is mapped to the screen, the 
window is unmapped. Any associated buffer change journal file is also 
closed and deleted. 

integer 

The integer to delete. Integers use no internal structures or resources so 
deleting a variable of type integer simply changes that variable to t 3 rpe 
unspecified. 

keyword 

The keyword to delete. Keywords use no internal structures or resources 
so deleting a variable of type keyword simply assigns to that variable the 
type unspecified. 
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DELETE 


learn 

The leam sequence you wish to delete. The memory used by the learn 
sequence is freed for later use. 

marker 

The marker you want to delete. The memory for the marker control 
structure is deleted also. 

pattern 

The pattern you wish to delete. The memory used by the pattern is freed 
for later use. If the pattern includes a reference to another pattern and 
there are no other references to that pattern, then that pattern is deleted 
as well. 

process 

The process you want to delete. The memory for the process control 
structure and the subprocess is deleted also. 

program 

The program you want to delete. The memory for the program control 
structure and the memory for the program code are deleted also. 

range 

The range that you want to delete. The memory for the range control 
structure is deleted also. The text in a range does not belong to the range. 
Rather, it belongs to the buffer in which it is located. A range is merely 
a way of memipulating sections of text within a buffer. When you delete 
a range, the text delimited by the range is not deleted. See the built-in 
procedure ERASE for a description of how to remove the text in a range. 

String 

The string you wish to delete. The memory used by the string is freed for 
later use. 

unspecified 

Deleting a variable of type unspecified is allowed but does nothing. 

widget 

The widget to be deleted. When you use the DELETE (widget) built- 
in, all variables and array elements that refer to the widget are set to 
unspecified. If an array element is indexed by the deleted widget, the 
array element is deleted as well. 

window 

The window you want to delete. Along with the window, the memory for 
the window control structure and the record history associated with the 
window are deleted. If you delete a window that is mapped to the screen, 
VAXTPU unmaps the window before deleting it. The screen appears just 
as it does when you use the built-in procedure UNMAP. 



VAXTPU Built-In Procedures 

DELETE 


DESCRIPTION Depending upon how many variables are referencing an entity, or how 

many other entities are associated with the entity you are delving, 
processing the built-in procedure DELETE can be time consuming. 
DELETE cannot be terminated by a CTRL/C. 

Any variables that reference the deleted entity are set to unspecified 
and all other entities that are associated with the deleted entity are also 
deleted. Use the built-in procedure DELETE with caution. 


SIGNALED 




ERRORS 

TPU$_TOOFEW 

ERROR 

DELETE requires one argument. 


TPU$_TOOMANY 

ERROR 

DELETE accepts only one 
argument. 


TPU$_BADDELETE 

ERROR 

You attempted to delete a 
constant. 


TPU$_DELETEFAIL 

WARNING 

DELETE could not delete the 
process. 


TPU$JNVBUFDELETE 

WARNING 

You cannot delete a permanent 
buffer. 


EXAMPLES 

D DELETE (main_buffer) 


This statement deletes the main buffer and any associated resources that 
VAXTPU allocated for the main buffer. As a result of this command, the 
SHOW (BUFFERS) command does not list MAIN_BUFFER as one of the 
buffers in your editing context. 

Q PROCEDURE user__delete_extra 

WRITE_FILE (extra_buf) ; 

DELETE (extra__window) ; 

DELETE (extra_buf)/ 

! Return the 11 lines from extra_window to the main window 
ADJUST_WINDOW (main_window, -11, 0); 

ENDPROCEDURE; 


This procedure writes the contents of EXTRA_BUF to a file (because you 
do not specify a file name, the associated file for the buffer is used) and 
then removes the extra window and buffer from your editing context. You 
must have previously created these structures and added them to your 
editing context in order for this procedure to execute successfully. 
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DELETE 


PROCEDURE sample_create_and_delete 

LOCAL example_widget, 

example__widget_name , 
example_hierarchy; 

example__hierarchy := SET (DRM__HIERARCHY, "mynode$duaO :[smith] example .uid") ; 
example__widget___name := "EXAMPLE_BOX”; 

example_widget ;= CREATE_WIDGET (example_widget_name, 

example__hierarchy, SCREEN, 
"user_callback___dispatch_routine") ; 

I 

I 

i 

DELETE (example_widget); 

ENDPROCEDURE; 

This code fragment creates a modal dialog box widget and later deletes 
it. For purposes of this example, the procedure user_callback_dispatch_ 
routine is assumed to be a user-written procedure that handles widget 
pgllhnrifg For a sample DECwindows User Interface Language (UIL) file 
to be used with VAXTPU code creating a modal dialog box widget, see the 
example in the description of the CREATE_WIDGET built-in. 


7-110 








VAXTPU Built-In Procedures 

EDIT 


EDIT 

Modifies a string according to the keywords you specify. EDIT is similar 
although not identical to the DCL lexical function F$EDIT. Differences between 
the built-in procedure and the lexical function are noted in the Description 
section. 


FORMAT 


r bufferl 'I 
< rangel I := EDIT 
[ stringl J 


r buffer2 1 
( ^ range2 
[ string2 j 
[.keywords^) 


keywordll,...] [,keyword2S 


PARAMETERS buffer2 

The buffer in which you want VAXTPU to edit text. Note that you cannot 
use the keyword NOT_IN_PLACE if you specify a buffer for the first 
parameter. 

range2 

The range in which you want VAXTPU to edit text. Note that you cannot 
use the keyword NOT_IN_PLACE if you specify a range for the first 
parameter. 

string2 

The string you want to modify. If you specify a return value, the returned 
string consists of the string you specify for the first parameter, modified 
in the way you specify in the second and subsequent parameters. If you 
specify IN_PLA.CE for the third parameter, EDIT makes the specified 
change to the string specified in the first parameter. Note that it string2 is 
a constant, IN_PLACE has no effect. 

keywordi 

A keyword specifying the editing operation you want to perform on the 
string. Valid ke3nvords and their meaning are as follows: 


Keyword 

Meaning 

COLLAPSE 

Removes all spaces and tabs. 

COMPRESS 

Replaces multiple spaces and tabs with a single space. 

TRIM 

Removes leading and trailing spaces and tabs. 

TRIM_LEADING 

Removes leading spaces and tabs. 

TRIM_TRAILING 

Removes trailing spaces and tabs. 

LOWER 

Converts ail uppercase characters to lowercase. 

UPPER 

Converts ail lowercase characters to uppercase. 

INVERT 

Changes the current case of the specified characters; 
uppercase characters become lowercase and lowercase 
characters become uppercase. 
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EDIT 


return values 


DESCRIPTION 


keyword2 

A keyword specifying whether VAXTPU quote characters are used as 
quote characters or as regular text. The vahd keywords are ON or OFF. 
The default is ON. 

keywords 

A keyword indicating where VAXTPU is to make the indicated change. 
The valid keywords and their meanings are as follows: 


Keyword 

Meaning 

IN_PLACE 

NOTJN_PLACE 

Makes the indicated change in place. This is the default. 

Leaves the specified string unchanged and returns a string 
that is the result of the specified editing. You cannot use 

NOT IN_PLACE if the first parameter is specified as a range 
or buffer. To use NOT_IN_PLACE, you must specify a return 
value for EDIT. 

Note that this kejnvord is ignored if string2 is a string constant. EDIT 
never edits string constants in place. It does return the edited string. 


bufferl 

A variable of type buffer pointing to the buffer containing the modified 
text, if you specify a buffer for the first parameter. The variable 
"retumed_buffer" points to the same buffer pointed to by the buffer 
variable specified as the first parameter. 

rangel 

A range containing the modified text, if you specify a range for the first 
parameter. The returned range spans the same text as the range specified 
as a parameter, but they are two separate ranges. If you subsequently 
change or delete one of the ranges, this has no effect on the other range. 

String 1 

A string containing the modified text, when you specify a string for the 
first parameter. EDIT can return a string even if you specify IN_PLACE. 

VAXTPU modifies the first parameter of the EDIT built-in in place. EDIT 

does not modify a literal string. 

By default, EDIT does not modify quoted text that occurs within a string. 
For example, the following code does not change the case of WELL: 

string__to_change := 'HE SANG "WELL”'; 
edit (string_texchange, LOWER); 

The variable string Jo _change has the value he sang "WELL". 

If you specify more than one of the TRIM keywords (TRIM, TRIM_ 
LEADING, TRIM_TRAILING), all of the TRIM operations you specify 
are performed. 
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If you specify more than one of the case conversion keywords (UPPER, 
LOWER, INVERT), the last keyword that you specify determines how the 
characters in the string are modified. 

If you specify both of the quote recognition keywords (ON, OFF), the last 
keyword you specify determines whether or not EDIT modifies quoted text. 

If you specify no keywords, EDIT does nothing to the passed string. 

You can disable the recognition of quotation marks and apostrophes as 
VAXTPU quote characters by using the keyword OFF as a parameter for 
EDIT. When you use the keyword OFF, VAXTPU preserves any quotation 
marks and apostrophes in the edited text and performs the editing tasks 
you specify on the text within the quotation marks and apostrophes. 

OFF may appear anywhere in the keyword list. It need not be the final 
parameter. 

If the string you specify has opening quotation marks but not closing 
quotation marks, the status TPU$_MISSINGQUOTE is returned. All text 
starting at the unclosed opening quotation mark and continuing to the 
end of the string is considered to be part of the quoted string and is not 
modified. 

EDIT is similar to the DCL lexical function F$EDIT. However, you should 
note the following differences: 

• EDIT modifies the characters in place while F$EDIT returns a result. 

• EDIT takes keywords as parameters while F$EDIT requires that the 
edit commands be specified by a string. 


SIGNALED 

ERRORS 


EXAMPLES 

D pn ;= "PRODUCT NAME 
EDIT (pn, LOWER); 
MESSAGE (pn); 


TPU$_MISSINGQUOTE 

ERROR 

Character string is missing 
terminating quotation marks. 

TPU$_TOOFEW 

ERROR 

EDIT requires at least one 
parameter. 

TPU$_TOOMANY 

ERROR 

You supplied keywords that are 
duplicative or contradictory. 

TPU$_ARGMISMATCH 

ERROR 

One of the parameters to EDIT is 
of the wrong data type. 

TPU$JNVPARAM 

ERROR 

One of the parameters to EDIT is 
of the wrong data type. 

TPU$_BADKEY 

WARNING 

You gave the wrong keyword to 
EDIT. 


II . 


These statements edit the string "PRODUCT NAME" by nhnngiTig it to 
lowercase, and display the edited string in the message window. 
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PROCEDURE user_edit_string (input_string) 
is := input string; 


EDIT (is, LOWER); 
MESSAGE (is); 
ENDPROCEDURE; 


This procedure shows a generalized way of changing any input string to 
lowercase. 


After compiling the preceding procedure, you can direct VAXTPU to print 
the lowercase word “zephjrr” in the message area by entering the following 
command: 


user_edit_string ("ZEPHYR") 

returned_value := EDIT (the_string, COLLAPSE, OFF, NOT_IN_PLACE); 


This statement removes all spaces and tabs from the string pointed to by 
the_string and does not treat quotation marks or apostrophes as quote 
characters. Returns the modified string in the variable returned_value, 
but does not change the string in the variable thejstring. 
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END_OF 

Returns a marker that points to the last character position in a buffer or a 
range. 

FORMAT 

marker := END OF (i 1) 

\ range )’ 

PARAMETERS 

buffer 

The buffer whose last character position you want to mark. 

range 

The range whose last character position you want to mark. 

return value 

A marker pointing to the last character position in a buffer or range. 

DESCRIPTION 

If you use the marker returned by the END_OF built-in as a parameter for 
the built-in procedure POSITION, the editing point moves to this marker. 

SIGNALED 

ERRORS 

TPU$_NEEDTOASSIGN ERROR END__OF must appear in the 

right-hand side of an assignment 
statement. 

TPU$_TOOFEW ERROR END_OF requires one argument. 

TPU$_TOOMANY ERROR END_OF accepts only one 

argument. 

TPU$_ARGMISMATCH ERROR You passed something other than 

a range or a buffer to END_OF. 


EXAMPLES 

Q the_end := END__OF (CURRENT^BUFFER) 

This assignment statement stores the last position in the current buffer in 
the variable the_end. 

g POSITION (END__OF (delete__range) ) 

This statement uses two built-in procedures to move your current 
character position to the end of delete_range. If delete jrange is in a visible 
buffer in which the cursor is located, the cursor position also moves to the 
end of deletejrange. 


7-115 














VAXTPU Built-In Procedures 

END OF 


PROCEDURE user_paste 
LOCAL paste_text; 

IF (BEGINNING__OF (paste_buffer) <> END_OF (paste__buffer) ) 

THEN 

COPY_TEXT (paste__buffer) ; 

ENDIF; 

ENDPROCEDURE; 

This procedure implements a simple INSERT HERE function. The 
variable paste Jbuffer points to a buffer that holds previously cut text. 
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ERASE 

Removes the contents of the range or buffer that you specify. 

FORMAT 

ERASE (1 1; 

' \ range y 

PARAMETERS 

buffer 

The buffer whose contents you want to remove. 

range 

The range whose contents you want to remove. 

DESCRIPTION 

When you erase a buffer, the contents of the buffer are removed. However, 
the buffer structure still remains a part of your editing context and the 
editing point remains in the buffer even if you remove the contents of 
the buffer. The space that was occupied by the contents of the buffer is 
returned to the system and is available for reuse. Only the end-of-buffer 
line remains. 

When you erase a range, the contents of the range are removed from the 
buffer. The range structure is still a part of your editing context. You can 
use the range structure later in your editing session to delimit an area of 
text within a buffer. 

Note that text does not belong to a range; it belongs to a buffer. Ranges 
are merely a way of manipulating portions of text within a buffer. For 
more information on ranges, see Chapter 2. 

SIGNALED 

ERRORS 

TPU$__TOOFEW ERROR ERASE requires one argument. 

TPU$__TOOMANY ERROR ERASE accepts only one 

argument. 

TPUSJNVPARAM ERROR The argument to ERASE is of the 

wrong type. 

TPU$_NOTMODIFIABLE WARNING You cannot erase text in an 

unmodiflable buffer. 
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EXAMPLES 

Q ERASE (main_buffer) 

This statement erases all the text in the buffer referenced by main_buffer. 
Since the buffer still exists, you can select the buffer using the POSITION 
built-in or map the buffer to a window. The procedure simply removes all 
text from the buffer. All markers in the buffer now mark the end of the 
buffer. 

g PROCEDURE user___remove_crlfs 

LOCAL crlf, 
here, 
cr_range; 

crlf := ASCII (13) + ASCII (10); 
here := MARK (NONE); 

POSITION (BEGINNING__OF (CURRENT_BUFFER) ) ; 

LOOP 

cr_range := SEARCH_QUIETLY (crlf, FORWARD, EXACT); 

EXITIF cr__range = 0; 

ERASE (cr_range); 

POSITION (cr__range) ; 

ENDLOOP; 

POSITION (here); 

ENDPROCEDURE; 


This procedure gets rid of embedded carriage-retum/line-feed pairs. 
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ERASE CHARACTER 



Deletes the number of characters you specify and optionally returns a string 
that represents the characters you deleted. 

FORMAT 

[string := ] ERASE_CHARACTER (integer) 

PARAMETER 

integer 

An expression that evaluates to an integer, which may be signed. The 
value indicates which characters, and how many of them, are to be erased. 

return value 

A string representing the characters deleted by ERASE_CHARACTER. 

DESCRIPTION 

ERASE_CHARACTER deletes up to the specified number of characters 
from the current line. If the argument to ERASE_CHARACTER is a 
positive integer, ERASE_CHARACTER deletes that many characters, 
starting at the current position and continuing toward the end of the line. 
If the argument is negative, ERASE_CHARACTER deletes characters 
to the left of the current character. It uses the absolute value of the 
parameter to determine the number of characters to delete. ERASE_ 
CHARACTER stops deleting characters if it reaches the beginning or the 
end of the line before deleting the specified number of characters. 

Using ERASE_CHARACTER may cause VAXTPU to insert padding 
spaces or blank lines in the buffer. ERASE^CHARACTER causes the 
screen manager to place the editing point at the cursor position if the 
current buffer is mapped to a visible window. (For more information on 
the distinction between the cursor position and the editing point, see 
Chapter 6.) If the cursor is not located on a character (that is, if the cursor 
is before the beginning of a line, beyond the end of a line, in the middle of 
a tab, or below the end of the buffer), VAXTPU inserts padding spaces or 
blank lines into the buffer to fill the space between the cursor position and 
the nearest text. 

ERASE_CHARACTER optionally returns a string containing the 
characters that it deleted. 

SIGNALED 

ERRORS 

TPU$_TOOFEW ERROR ERASE_CHARACTER requires 

one argument. 

TPU$_TOOMANY ERROR ERASE^CHARACTER accepts 

only one argument. 

TPU$JNVPARAM ERROR The argument to ERASE_ 

CHARACTER must be an integer. 
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TPU$_NOCURRENTBUF 

TPU$_NOTMODIFIABLE 


WARNING There is no current buffer to erase 
characters from. 

WARNING You cannot modify an unmodifiable 
buffer. 


EXAMPLES 

D take_out_chars := ERASE_CHARACTER (10) 

This assignment statement removes the current character and the nine 
characters following it and copies them in the string variable take_out_ 
chars. If there are only five characters following the current character, 
then this statement deletes only the current character and the five 
following it. It does not delete characters on the next fine as well. 


prev_chars := ERASE_CHARACTER (-5) 

This assignment statement removes the five characters preceding the 
current character and copies them in the string variable prev_chars. 

! This procedure deletes the character to the 
! left of the current character. If at the 
! beginning of a line, it appends the current 
! line to the previous line. 

PROCEDURE user_delete_key 

LOCAL deleted__char; 

deleted_char := ERASE_CHARACTER (-1); 

IF deleted_char = ! nothing deleted 

THEN 

APPEND_LINE; 

ENDIF; 

ENDPROCEDURE; 

This procedure deletes the character to the left of the editing point. If 
the editing point is at the beginning of a line, the procedure appends the 
current line to the previous line. 


7-120 










VAXTPU Built-In Procedures 

ERASE_LINE 


ERASE LINE 



Removes the current line from the current buffer. 

ERASE_LINE optionally returns a string containing the text of the deleted line. 

FORMAT 

[string := ] ERASE_LINE 

PARAMETERS 

None. 

return value 

A string containing the text of the deleted line. 

DESCRIPTION 

ERASE_LINE deletes the current line, optionally storing the deleted 
text in a string before doing so. The current position moves to the first 
character of the line following the deleted line. 

Using ERASE_LINE may cause VAXTPU to insert padding spaces or blank 
lines in the buffer. ERASE_LINE causes the screen manager to place the 
editing point at the cursor position if the current buffer is mapped to a 
visible window. (For more information on the distinction between the 
cursor position and the editing point, see Chapter 6.) If the cursor is not 
located on a character (that is, if the cursor is before the beginning of a 
line, beyond the end of a line, in the middle of a tab, or below the end of 
the buffer), VAXTPU inserts padding spaces or blank lines into the buffer 
to fill the space between the cursor position and the nearest text. 

If the screen manager inserts padding spaces, ERASE_LINE deletes these 
spaces when it deletes the line. The spaces appear in the returned string. 
If the screen manager inserts padding lines into the buffer, ERASE_LINE 
deletes only the last of these lines. 

SIGNALED 

ERRORS 

TPU$_TOOMANY ERROR ERASE_LiNE accepts no 

arguments. 

TPU$_NOTMODIFIABLE WARNING You cannot erase a line in an 

unmodifiable buffer. 

TPU$_NOCURRENTBUF ERROR You must select a buffer before 

erasing a line. 
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EXAMPLES 

Q ERASE_LINE 

This statement removes the current line from the current buffer. 

§ take_out_line ;= ERASE_LINE 

This statement removes the current line from the current buffer and stores 
the string of characters representing that line in the variable take_out_ 
line. 
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ERROR 

Returns a keyword for the latest error. 

FORMAT 

keyword := ERROR 

PARAMETERS 

None. 

return value 

A keyword representing the most recent error. 

DESCRIPTION 

The possible error and warning codes for each built-in procedure are 
included in the description of each built-in procedure. Appendix C contains 
an alphabetized list of all the possible completion codes and severity levels 
in VAXTPU. The VMS System Messages and Recovery Procedures Reference 
Manual includes all the possible completion codes for VAXTPU as well as 
the appropriate explanations and suggested user actions. 

The value returned by ERROR is only meaningful inside an error handler, 
after an error has occurred. The value outside an error handler is 
indeterminate. 

Although ERROR behaves much like a built-in, it is actually a VAXTPU 
language element. 

ERROR is evaluated for correct syntax at compile time. In contrast, 
VAXTPU procedures are usually evaluated for a correct parameter coimt 
and parameter types at execution. 

SIGNALED 

ERROR 

ERROR is a language element and has no completion codes. 


EXAMPLE 

PROCEDURE strip_blanks 

! Remove trailing blanks from all the lines in a buffer 

LOCAL blank_chars, 

blank_pattern, 

blank_range; 

ON__ERROR 

IF ERROR = TPU$_STRNOTFOUND 
THEN 

RETURN; 

ELSE 

MESSAGE (ERROR_TEXT); 

ABORT; 

ENDIF; 

ENDON ERROR; 
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blank_chars := ASCII (32) + ASCII (9); 

blank_pattern ;= (SPAN (blank_chars) 0 blank_range) + LINE__END; 

LOOP 

SEARCH (blank_pattern, FORWARD); 

POSITION (BEGINNING_OF (blank_range)) ; 

ERASE (blank_range); 

ENDLOOP; 

ENDPROCEDURE; 

This procedure uses the ERROR language element to determine the error 
that invoked the error handler. If the error was that SEARCH could 
not find the specified string, then the procedure returns normally. (For 
more information on error handlers, see Chapter 3 and the descriptions of 
ABORT and RETURN in this chapter.) If the error was something else, 
then the text of the error message is written to the MESSAGES buffer and 
any executing procedures are terminated. 


7-124 











VAXTPU Built-In Procedures 

ERROR LINE 


ERROR LINE 



Returns the line number for the latest error. 

FORMAT 

integer := ERROR_LINE 

PARAMETERS 

None. 

return value 

An integer representing the line number of the most recent error. 

DESCRIPTION 

ERROR__LINE returns the line number at which the error or warning 
occurs. If a procedure was compiled from a buffer or range, ERROR_LINE 
returns the line number within the buffer. This may be different from the 
line number within the procedure. If the procedure was compiled from a 
string, ERROR_LINE returns 1. 

The value returned by ERROR_LINE is only meaningful inside an error 
handler, after an error has occurred. The value outside an error handler is 
indeterminate. 

Although ERROR__LINE behaves much like a built-in, it is actually a 
VAXTPU language element. 

ERROR_LINE is evaluated for correct S3nitax at compile time. In contrast, 
VAXTPU procedures are usually evaluated for a correct parameter coimt 
and parameter types at execution. 

SIGNALED 

ERROR 

ERROR is a language element and has no completion codes. 


EXAMPLE 

PROCEDURE strip_blanks 

! Remove trailing blanks from all the lines in a buffer 

LOCAL blank_chars, 

blank_pattern, 

blank__range; 

ON_ERROR 

MESSAGE (ERROR_TEXT); 

MESSAGE ("Error on line ” + STR (ERROR_LINE)); 

RETURN; 

ENDON_ERROR; 

blank_chars := ASCII (32) + ASCII (9); 

blank_pattern := (SPAN (blank_chars) @ blank_range) + LINE_END; 
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LOOP 

SEARCH (blank_pattern, FORWARD); 
POSITION (blank_range); 

ERASE (blank_range); 

ENDLOOP; 

ENDPROCEDURE; 


This procedure uses the ERROR^LINE built-in procedure to report the 
line in which the error occurred. 
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ERROR TEXT 



Returns the text of the latest error message. 

FORMAT 

string := ERROR_TEXT 

PARAMETERS 

None. 

return value 

A string containing the text of the most recent error message. 

DESCRIPTION 

ERROR_TEXT returns the text for the most recent error or warning. 

The possible error and warning codes for each built-in procedure are 
included in the description of each built-in procedure. Appendix C contains 
an alphabetized list of all the possible completion codes and severity levels 
in VAXTPU. The VMS System Messages and Recovery Procedures Reference 
Manual includes all the possible completion codes for VAXTPU as well as 
the appropriate explanations and suggested user actions. 

The value returned by ERROR_TEXT is meaningful only inside an error 
handler, after an error has occurred. The value outside an error handler is 
indeterminate. 

Although ERROR_TEXT behaves much like a built-in, it is actually a 
VAXTPU language element. 

ERROR_TEXT is evaluated for correct syntax at compile time. In contrast, 
VAXTPU procedures are usually evaluated for a correct parameter count 
and parameter t3rpes at execution. 

SIGNALED 

ERROR 

ERROR_TEXT is a language element and has no completion codes. 


EXAMPLE 

PROCEDURE strip__blanks 

! Remove trailing blanks from all the lines in a buffer 

LOCAL blank__chars, 

blank__pattern, 

blank__range; 

ON__ERROR 

MESSAGE (ERROR_TEXT); 

MESSAGE ("Error on line " + STR (ERROR_LINE)); 

RETURN; 

ENDON__ERROR; 

blank_chars := ASCII (32) + ASCII (9); 

blank_pattern := (SPAN (blank_chars) @ blank__range) + LINE_END; 
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LOOP 

SEARCH (blank_pattern, FORWARD); 
POSITION (BEGINNING^OF {blank_range)); 
ERASE (blank_range); 

ENDLOOP; 

ENDPROCEDURE; 


This procedure uses the built-in procedure ERROR_TEXT to report what 
happened and where. 
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EXECUTE 


Does one of the following: 

• Executes programs that you have previously compiled 

• Compiles and then executes any executable statements in a buffer, a 
range, or a string 

• Replays a learn sequence 

• Executes a program bound to a key 


FORMAT 


buffer 


key-name 


EXECUTE (< 


learn 

program 

range 

string 


, key-map-list-name 
, key-map-name 




PARAMETERS buffer 

The buffer that you want to execute. 

key-name 

The VAXTPU key name for a key or a combination of keys. VAXTPU 
locates and executes the definition bound to the key. 

key-map-list-name 

The name of the key map list in which the key is defined. This optional 
parameter is only valid when the first parameter is a key name. If you 
specify a key map list as the second parameter, VAXTPU uses the first 
definition of the key specified by keyjiame found in any of the key maps 
specified by the key map list. If you do not specify any value for the second 
parameter, VAXTPU uses the first definition of the key specified by key_ 
name found in the key map list bound to the current buffer. 

key-map-name 

The name of the key map in which the key is defined. This optional 
parameter is valid only when the first parameter is a key name. Use this 
parameter only if the key specified by the first parameter is defined in 
the key map specified as the second parameter. If you do not specify any 
value for the second parameter, VAXTPU uses the first definition of the 
key specified by keyjiame found in the key map list bound to the current 
buffer. 

learn 

The leam sequence that you WEUit to replay. 


program 

The program that you want to execute. 
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range 

The range that you want to execute. 

string 

The string that you want to execute. 


DESCRIPTION EXECUTE performs different actions depending upon the data type of the 

parameter. 

If the parameter is a string or the contents of a buffer or range, it must 
contain only valid VAXTPU statements. Otherwise, you get an error 
message and no action is taken. See the description of the built-in 
procedure COMPILE for restrictions and other information on compiling 
strings or the contents of a buffer or range. When you pass a string to 
EXECUTE, the string cannot be longer than 256 characters. 

Procedures are usually executed by entering the name of a compiled 
procedure at the appropriate prompt from your editing interface, or by 
calling the procedure from within another procedure. However, it is 
possible to execute procedures with the built-in procedure EXECUTE if 
the procedure returns a data t 3 rpe that is a valid pareimeter. 

In the following example, the procedure test returns a program data type. 
If you execute a bxiffer or range that contains the following code, VAXTPU 
compiles and executes the procedure test, a program data type is returned, 
the program is then used as the parameter for the built-in procedure 
EXECUTE, and the string "abc" is written to the message area. 

PROCEDURE test 

! After compiling the string 'MESSAGE ("abc")', 

! VAXTPU returns a program that is the compiled 
! form of the string. 

RETURN COMPILE ('MESSAGE ("abc")'); 

ENDPROCEDURE; 

! The built-in procedure EXECUTE executes the 
! program returned by the procedure "test." 

EXECUTE (test); 


SIGNALED 




ERRORS 

TPU$_NODEFINITION 

WARNING 

There is no definition for this key. 

TPU$_REPLAYWARNING 

WARNING 

Inconsistency during the execution 
of a learn sequence ... sequence 
is proceeding. 


TPU$_REPLAYFAIL 

WARNING 

Inconsistency during the execution 
of a learn sequence ... execution 
stopped. 


TPU$_RECURLEARN 

ERROR 

You cannot execute learn 
sequences recursively. 
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TPU$_CONTROLC 

ERROR 

The execution of the command 
terminated because you pressed 
CTRL/C. 

TPU$_EXECUTEFAIL 

WARNING 

Execution of the indicated item 
has halted because it contains an 

error. 

TPU$_COMPILEFAIL 

WARNING 

Compilation aborted because of 
syntax errors. 

TPU$_ARGMISMATCH 

ERROR 

A parameter’s data type is 
unsupported. 

TPU$_TOOFEW 

ERROR 

Too few arguments. 

TPU$_TOOMANY 

ERROR 

Too many arguments. 

TPU$_NOTDEFINABLE 

WARNING 

Key cannot be defined. 

TPU$_NOCURRENTBUF 

WARNING 

Key map or key map list not 
specified, and there is no current 
buffer. 

TPU$_NOKEYMAP 

WARNING 

Key map or key map list not 
defined. 

TPU$_NOTMODIFIABLE 

WARNING 

You cannot copy text into an 
unmodifiable buffer. 

TPU$_NODEFINITION 

WARNING 

Key not defined. 


EXAMPLES 

Q EXECUTE (user_program) 

This statement executes the executable statements in the program named 
user_program. 

g EXECUTE (main_buffer) 

This statement first compiles the contents of mainjbuffer and then 
executes any executable statements. If you have any text in the main 
buffer other than VAXTPU statements, you get an error message. If there 
are procedure definitions in main_buffer, they are compiled, but they are 
not executed until you run the procedure (either by entering the procedure 
name after the appropriate prompt from your interface or by calling the 
procedure from within another procedure). 

g EXECUTE (RET_KEY, "TPU$KEY_MAP_LIST"); 

This statement first finds the program bound to the return key in the 
default VAXTPU key map list, and then executes the code or learn 
sequence found. 

Q PROCEDURE user_do 

coinmand_string := READ__LINE ("Enter VAXTPU command to execute; "); 

EXECUTE (commandostring); 

ENDPROCEDURE; 


This procedure prompts the user for a VAXTPU command to execute and 
then executes the command. 
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PROCEDURE user_tpu (TPU_COMMAND) 


SET (INFORMATIONAL, ON); 
EXECUTE (TPU_COMMAND) ; 

SET (INFORMATIONAL, OFF); 
ENDPROCEDURE; 


This procedure executes a command with informational messages turned 
on, and then turns the informational messages off after the command is 
executed. You must replace the parameter TPU_COMMAND with the 
desired VAXTPU statement. 
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EXIT 

Terminates the editing session and writes out any modified buffers that have 
associated fiies. VAXTPU queries you for a fiie name for any buffer that you 
have modified that does not aiready have an associated fiie. 

Buffers that have the NO WRITE attribute are not written out. See SET (NO 
WRITE, buffer). 

FORMAT 

EXIT 

PARAMETERS 

None. 

DESCRIPTION 

If you do not modify a buffer, VAXTPU does not write out the next version 
of the file associated with the buffer when you use the built-in procedure 
EXIT to exit from VAXTPU. 

If you modify a buffer that does not have an associated file name, (because 
you did not specify a file name for the second parameter of 
CREATE_BUFFER), VAXTPU asks you to specify a file name if you want 
to write the buffer. If you press the RETURN key rather than entering a 
file name, the modified buffer is discarded. VAXTPU queries you about all 
modified buffers that do not have associated file names. The order of the 
query is the order in which the buffers were created. 

Journal files (if any) are deleted upon exiting. 

If an error occurs while you are trying to exit, the exit halts and control 
returns to the editor. 

SIGNALED 

ERRORS 

TPU$_EXITFAIL WARNING The EXIT did not complete 

successfully because of problems 
writing modified buffers. 

TPU$_TOOMANY ERROR EXIT takes no arguments. 
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EXAMPLE 

EXIT 

This ends the editing session and writes out any modified buffers that 
have associated file names. If you have modified a buffer that does not 
have an associated file name, VAXTPU queries you with the following 
prompt; 

Enter a file name to write buffer "buffer_name"; else press RETURN: 

Enter a file name such as TEXT_FILE.LIS if you want the contents of the 
buffer written to a file. Press the RETURN key if you do not want to write 
the contents of the buffer to a file. 
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EXPAND NAME 



Returns a string that contains the names of any VAXTPU giobai variabies, 
keywords, or procedures (buiit-in or user-written) that begin with the string 
that you specify. VAXTPU searches its internai symbol tables to find a match, 
using your input string as the directive for the match. 

FORMAT 

' .ALL \ 

strlng2 := EXPAND_NAME (stringl ^ [pr^EDURES V 

. ! VARIABLES ) 

PARAMETERS 

stringl 

An expression that evaluates to a string. If the string contains one or 
more asterisks (*) or percent signs (%), then the string is a wildcard 
specification of the VAXTPU names to match. An asterisk matches zero or 
more characters and a percent sign matches exactly one character. If the 
string does not contain any asterisks or percent signs, then the string is 
the initial substring of a VAXTPU name. 

ALL 

A keyword specif 3 dng that you want VAXTPU to match all names. 

KEYWORDS 

A keyword specifying that you want VAXTPU to match only keyword 
names. 

PROCEDURES 

A keyword specifying that you want VAXTPU to match only procedure 
names. 

VARIABLES 

A keyword specifying that you want VAXTPU to match only global variable 
names. EXPAND_NAME does not expand the names of local variables. 

DESCRIPTION 

If there are no matches for the substring you specify, a null string is 
returned and a warning (TPU$_NONAMES) is signaled. If only one 
VAXTPU name matches the substring you specify, the name is returned 
with no trailing space. If more than one VAXTPU name matches your 
substring, all of the matching names are returned. The matching neunes 
are returned as a concatenated string with words separated by a single 
space. Multiple names signal a warning (TPU$_MULTIPLENAMES). 

Use EXPAND_NAME in procedures that perform command completion or 
that interpret abbreviated names. 

EXPAND_NAME does not expand the names of local variables. 
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SIGNALED 

ERRORS 

TPU$_NONAMES 

WARNING 

No names were found matching 
the one requested. 


TPU$_MULTIPLENAMES 

WARNING 

More than one name matching the 
one requested was found. 


TPU$_NEEDTOASSIGN 

ERROR 

EXPAND_NAME must appear 
on the right-hand side of an 
assignment statement. 


TPU$_TOOFEW 

ERROR 

EXPAND_NAME requires two 
arguments. 


TPU$_TOOMANY 

ERROR 

EXPAND_NAME accepts no more 
than two arguments. 


TPU$JNVPARAM 

ERROR 

One of the arguments you passed 
to EXPAND_NAM E has the wrong 
data type. 


TPU$_BADKEY 

WARNING 

You specified an invalid keyword 
as the second argument. 


EXAMPLES 

Q full_name := EXPAND_NAME ("MOVE", ALL) 

This assignment statement returns the following VAXTPU names in the 
string fulljiame: 

MOVE_HORIZONTAL MOVE_VERTICAL MOVE_TEXT 
g full__name ;= EXPAND_NAME ("*EXACT", KEYWORDS) 

This assignment statement returns the following VAXTPU keyword names 
in the string fulljiame: 

EXACT NONEXACT 

g full_name := EXPAND_NAME ("%%", KEYWORDS) 

This assignment statement returns the following VAXTPU keyword names 
in the string fulljiame: 

ON UP DO E5 F6 E4 F7 E6 El E3 E2 F8 F9 

These are all the keywords whose names are two characters long. 

Q PROCEDURE user__quick_parse (abbreviated___name) 

ON_ERROR 

IF ERROR = TPU$__NONAMES 
THEN 

MESSAGE ("No such procedure."); 

ELSE 

IF ERROR = TPU$_MULTIPLENAMES 
THEN 

MESSAGE ("Ambiguous abbreviation."); 

ENDIF; 

ENDIF; 

RETURN; 

ENDON ERROR; 
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expanded_name := EXPAND_NAME (abbreviated_name, PROCEDURES); 
MESSAGE ("The procedure is " + expanded__name + 

ENDPROCEDURE; 


This procedure uses the string that you enter as the parameter, and puts 
the expanded form of a valid VAXTPU procedure name that matches 
the string in the message area. If the initial string matches multiple 
procedure names, or if it is not a valid VAXTPU procedure name, an 
explanatory message is written to the message area. 
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FAO 


Invokes the Formatted ASCII Output ($FAO) system sen/ice to convert a 
control string to a formatted ASCII output string. By specifying arguments for 
FAO directives in the control string, you can control the processing performed 
by the $FAO system service. The built-in procedure FAO returns a string that 
contains the formatted ASCII output. 

For complete information on the $FAO system service, see the VMS System 
Services Reference Manual. 


FORMAT 


string2 := FAO 


(string 1 [, 


integerl 

Strings 


( integer_n 
\ string_n 



PARAMETERS stringl 

A string, a variable name representing a string constant, or an expression 
that evaluates to a string, that consists of the fixed text of the output 
string and FAO directives. 

Some FAO directives that you can use as part of the string are the 
following: 

!AS Inserts a string as is 

!OL Converts a longword to octal notation 

!XL Converts a longword to hexadecimal notation 

!ZL Converts a longword to decimal notation 

!UL Converts a longword to decimal notation without adjusting for negative 

number 

!SL Converts a longword to decimal notation with negative numbers 

converted properly 

!/ Inserts a new line (carriage return/line feed) 

L Inserts a tab 

!} Inserts a form feed 

I! Inserts an exclamation mark 

!%S Inserts an s if the most recently converted number is not 1 

!%T Inserts the current time if you enter 0 as the parameter (you cannot pass 

a specific time because VAXTPU does not use quadwords) 

!%D Inserts the current date and time if you enter 0 as the parameter (you 

cannot pass a specific date because VAXTPU does not use quadwords) 

integerl... integer_n 

An expression that evaluates to an integer. $FAO uses these integers as 
arguments to the FAO directives in string2 to form stringl. 

Strings... string_n 

An expression that evaluates to a string. $FAO uses these strings as 
arguments to the FAO directives in string2 to form stringl. 
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return value A string containing the output you specify in ASCII format. 


DESCRIPTION FAO returns a formatted string, constructed according to the rules of the 

$FAO system service. The control string directs the formatting process, 
and the optional arguments are values to be substituted into the control 
string. 

To ensure that you get meaningful results, you should use the !AS directive 
for strings and the !OL, !XL, !ZL, !UL, or !SL directive for integers. 


SIGNALED 


ERRORS 

TPU$JNVFAOPARAM 

WARNING 

Argument was not a string or an 
integer. 


TPU$_NEEDTOASSIGN 

ERROR 

FAO must appear on the right- 
hand side of an assignment 
statement. 


TPU$JNVPARAM 

ERROR 

The first argument to FAO must be 
a string. 


TPU$_TOOFEW 

ERROR 

FAO requires at least one 
parameter. 


EXAMPLES 

Q date_and__time := FAO ("!%D",0) 

This assignment statement stores the current date and time in the 
variable datejindjime, 

§ PROCEDURE user__fao_conversion (count) 

report := FAO ("number of forms = !SL", count); 

MESSAGE (report); 

ENDPROCEDURE; 

This procedure uses the FAO directive !SL in a control string to convert 
the number equated to the variable count to a string. The converted string 
is stored in the variable report and then written to the message area. 

§ PROCEDURE user__error_message (strng, line, col) 
error_count := error_count + 1; 

MESSAGE (FAO ("!AS at line !UL column !UL", strng, line, col)); 

ENDPROCEDURE; 

This procedure formats the message that is being written to the message 
area. The message tells the user the line and column at which an error 
occurred. 
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FILE PARSE 



Performs the equivalent of the DCL F$PARSE lexical function. That is, it calls 
the RMS service SPARSE to parse a file specification and to return either an 
expanded file specification or the file specification field that you request. 

FILE_PARSE returns a string that contains the expanded file specification or 
the field you specify. If you do not provide a complete file specification, FILE_ 
PARSE supplies defaults in the return string, as described in the Description 
section. 

If an error occurs during the parse, FILE_PARSE returns a null string. 

FORMAT 

Strings := FILE_PARSE (filespec [, stringl 

1 string2 [, NODE ] 

H. DEVICE] 

1 DIRECTORY] 

1 NAME]], TYPE] 

], VERSION]]]) 

PARAMETERS 

filespec 

The file specification to be parsed. 

stringl 

A default file specification. Any field of the file specification that you 
provide with this parameter is substituted in the output string if that field 
is missing in the filespec, 

string2 

A related file specification. Some of the fields in the related file 
specification are substituted in the output string if a field is missing 
from both the filespec and the stringl parameters. 

NODE 

Ke5rword specifying that FILE_PARSE should return a file specification 
including the node. For more information on using the optional ke3rword 
parameters to FILE_PARSE, see the Description section. 

DEVICE 

Ke5nvord specifying that FILE_PAESE should return a file specification 
including the device. For more information on using the optional keyword 
parameters to FILE_PARSE, see the Description section. 

DIRECTORY 

Keyword specifying that FILE^PARSE should return a file specification 
including the directory. For more information on using the optional 
keyword parameters to FILE_PARSE, see the Description section. 
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return value 

NAME 

Keyword specifying that FILE_PARSE should return a file specification 
including the name. For more information on using the optional ke5word 
parameters to FILE_PARSE, see the Description section. 

TYPE 

Keyword specifying that FILE_PAESE should return a file specification 
including the type. For more information on using the optional kejword 
parameters to FILE_PARSE, see the Description section. 

VERSION 

Ke3nvord specifying that FILE_PARSE should return a file specification 
including the version. For more information on using the optional keyword 
parameters to FILE_PAKSE, see the Description section. 

A string containing an expanded file specification or the file specification 
field you specify. 

DESCRIPTION 

The built-in procedure FILE_PAESE allows you to parse file specifications 
using the RMS service $PARSE. For more information on the $PARSE 
service, see the VMS Record Management Services Manual. 

If you do not supply any of the optional parameters, FILE_PARSE returns 
the device, directory, file name, and type of the file specified in filespec. 

Specify the first three parameters as strings. The remaining parameters 
are keywords. Logical names and device names must terminate with a 
colon. If you omit optional parameters to the left of a given parameter, you 
must include null strings as place holders for the missing parameters. 

You can specify as many of the ke3nvords for field names as you wish. If 
one or more of these keywords are present, FILE_PARSE returns a string 
containing only those fields requested. The fields are returned in normal 
file specification order. The normal delimiters are included, but there are 
no other characters separating the fields. For example, suppose you direct 
VAXTPU to execute the following statements: 

result := FILE_PARSE (" junk.txtNODE, DEVICE, TYPE); 
MESSAGE (result); 

Suppose, too, that the node is WORK and the device is DISKl. When the 
statements execute, VAXTPU displays the following string: 

work::diskl:.txt 

If you omit the file name, type, or version number, FILE_PARSE supplies 
defaults, first from stringl and then from string 2 . If you do not provide 
these parameters, FILE_PARSE returns a null specification for these 
fields. 

The FILE_PARSE built-in procedure does not check that the file exists. It 
merely parses the file specification provided, and returns the portions of 
the resultant file specification requested. 

You can use wildcard directives in supplying file specifications. 
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SIGNALED 

ERRORS 

TPU$_PARSEFAIL 

WARNING 

RMS detected an error while 
parsing the file specification. 


TPU$_NEEDTOASSIGN 

ERROR 

FILE_PARSE must appear on the 
right-hand side of an assignment 
statement. 


TPU$_TOOFEW 

ERROR 

FILE__PARSE requires at least one 
argument. 


TPU$JNVPARAM 

ERROR 

One of the parameters to FILE_ 
PARSE has the wrong data type. 


TPU$_BADKEY 

ERROR 

You specified an invalid keyword 
to FILE__PARSE. 


EXAMPLES 

D spec := FILE_PARSE ("program.pass", "[abbott]") 

This assignment statement calls RMS to parse and return a full file 
specification for the file PROGRAM.PAS. The second parameter provides 
the name of the directory in which the file can be found. 

§ PROCEDURE user_start_journal 
! Default journal name 

! Auxiliary journal name derived from file name 

LOCAL default_journal_name, 
aux_ j ournal_name; 

IF (GET__INFO (COMMAND_LINE, "journal") = 1) 

AND 

(GET_INFO (COMMAND_LINE, "read_only") <> 1) 

THEN 

aux_journal__name := GET__INFO (CURRENT_BUFFER, "file_name") ; 

IF aux_journal_name = "" 

THEN 

aux_journal_name ;= GET_INFO (CURRENT_BUFFER, "output_file"); 

ENDIF; 

IF aux_journal_name = 0 
THEN 

aux__journal_name := ""; 

ENDIF; 

IF aux_journal_name = "" 

THEN 

default__journal_name := "user.TJL"; 

ELSE 

default__journal_name := ".TJL"; 

ENDIF; 

journal_file := GET_INFO (COMMAND__LINE, " journal__file") ; 
journal_file := FILE__PARSE (journal_file, default_journal_name, 

aux_journal_name); 

JOURNAL_OPEN (journal_file); 

ENDIF; 

ENDPROCEDURE; 
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FILE SEARCH 



Calls the RMS service SSEARCH to search a directory and return the partial 
or full file specification for the file that you specify. 

FILE_SEARCH returns a string containing the resulting file specification or a 
null string if no file Is found. 

FORMAT 

Strings := FILE_SEARCH (filespec 

1 string 1 
[, string2 
[, NODE ] 

1 DEVICE ] 

1 DIRECTORY] 

[, NAME]], TYPE] 

] VERSION] ]]) 

PARAMETERS 

filespec 

The file specification you want to find. If you omit the device or directory 
names, FILE_SEAECH supphes defaults from the optional parameters 
or from your current default device and directory if you do not supply 
optional parameters. 

String 1 

A default file specification. If you fail to specify a field in filespec and that 
field is present in the default file specification, VAXTPU uses the field from 
stringl when searching for the file. 

string2 

A related file specification. If you fail to specify a field in filespec and 
stringl and that field is present in the related file specification, VAXTPU 
uses the field from string 2 when searching for the file. 

NODE 

Keyword specifying that FILE_SEAKCH should return a file specification 
including the node. For more information on using the optional ke3nvord 
parameters to FILE_SEARCH, see the Description section. 

DEVICE 

Ke3rword specifying that FILE_SEARCH should return a file specification 
including the device. For more information on using the optional keyword 
parameters to FILE_SEARCH, see the Description section. 

DIRECTORY 

Keyword specifying that FILE_SEARCH should return a file specification 
including the directory. For more information on using the optional 
keyword parameters to FILE_SEARCH, see the Description section. 
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return value 

NAME 

Keyword specifying that FILE_SEARCH should return a file specification 
including the name. For more information on using the optional keyword 
parameters to FILE_SEARCH, see the Description section. 

TYPE 

Keyword specifying that FILE_SEARCH should return a file specification 
including the type. For more information on using the optional kejrword 
parameters to FILE_SEARCH, see the Description section. 

VERSION 

Ke5nvord specifying that FILE_SEARCH should return a file specification 
including the version. For more information on using the optional ke3nvord 
parameters to FILE_SEAKCH, see the Description section. 

A string containing the partial or full file specification you request from 
$SEARCH. 

DESCRIPTION 

The built-in procedure FILE_SEARCH allows you to search for files 
in a directory using the $SEARCH routine. You must use this built- 
in procedure multiple times with the same parameter to get all of the 
occurrences of a file name in a directory. See the VMS Record Management 
Services Manual for more information on $SEAKCH. 

Specify the first three parameters as strings. The remaining parameters 
are keywords. Logical names and device names must terminate with a 
colon. If you omit optional parameters to the left of a given parameter, you 
must include null strings as place holders for the missing parameters. 

You can specify as many of the keyword parameters (such as NODE or 
DEVICE) as you wish. If one or more of these keywords are present, 
FILE_SEARCH returns only those fields requested in the keyword list, not 
the full file specification. The fields appear in the same order as they do in 
a full file specification. There is no separator between fields. 

If you omit all the optional parameters, FILE_SEARCH returns the device, 
directory, file name, type, and version. 

Unlike the FILE_PARSE built-in, FILE_SEARCH verifies that the file you 
specify exists. 

If FILE_SEARCH does not find a matching file, or if the built-in finds one 
or more matches but is invoked again and does not find another match, 
FILE SEARCH returns a null string but not an error status. Thus, the 
null string can act as an “end of matching files” indicator. When FILE_ 
SEARCH returns the status TPU$_SEARCHFAIL, look in the message 
buffer to see why the search was unsuccessful. 
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SIGNALED 

ERRORS 

TPU$_SEARCHFAIL 

WARNING 

RMS detected an error while 
searching for the file. 


TPU$_TCX)FEW 

ERROR 

FILE_SEARCH requires at least 
one parameter. 


TPU$_NEEDTOASSIGN 

ERROR 

FILE_SEARCH must be on the 




right-hand side of an assignment 
statement. 


TPU$JNVPARAM 

ERROR 

One of the arguments you passed 
to FILE_SEARCH has the wrong 
type. 


TPU$_BADKEY 

WARNING 

One of the keyword arguments 
you specified is not one of those 
FILE_SEARCH accepts. 


EXAMPLES 

D fil := FILE_SEARCH ("SYS$SYSTEM:*.EXE") 

Each time this assignment statement is executed, it returns a string 
containing the resulting file specification of an EXE file in SYS$SYSTEM. 
Because no version number is specified, only the latest version is returned. 
When you get a null string, it means there are no more EXE files in the 
directory. 


§ PROCEDURE user_collect_rnos 
LOCAL filename; 
filename := FILE_SEARCH ; 

LOOP 

filename := FILE_SEARCH ("*.RNO", NAME, TYPE); 

EXITIF filespec = 

CREATE_BUFFER (filename, filename); 

ENDLOOP,• 

ENDPROCEDURE; 

This procedure is similar to the previous procedure. It makes use of the 
fact that you are looking for files in the current directory and that FILE_ 
SEARCH can return parts of the file specification to eliminate the call to 
FILE_PARSE. 
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FILL 

Reformats the text in the specified buffer or range so that the lines of text are 
approximately the same length. 

FORMAT 

FILL ( I string [, integerl [, integer2 

[, integers]]]]) 

PARAMETERS 

buffer 

The buffer whose text you want to fill. 

range 

The range whose text you want to fill. 

String 

The list of additional word separators. The space character is always a 
word separator. 

integerl 

The vedue for the left margin. The left margin value must be at least 1 
and must be less than the right margin value. Defaults to the buffer’s left 
margin. 

integer2 

The value for the right margin. This value defaults to the same value as 
the buffer’s right margin. Integer 2 must be greater than the left margin 
and cannot exceed the maximum record size for the buffer. 

integers 

The value for the first line indent. This value modifies the left margin of 
the first filled fine. It may be positive or negative. The result of adding 
the first line indent to the left margin must be greater than 1 and less 
than the right margin. Defaults to 0 . 

DESCRIPTION 

FILL recognizes two classes of characters, text characters and word 
separators. Any character may be a word separator and any character 
other than the space character may be a text character. The space 
character is always a word separator, even if it is not present in the 
second parameter passed to FILL. 

A word is a contiguous sequence of text characters, all of which are 
included on the same line, immediately preceded by a word separator or 
a line break, and immediately followed by a word separator or line break. 
If the first or last character in the specified range is a text character, 
that character marks the beginning or end of a word, regardless of £uiy 
characters outside the range. Filling a range that starts or ends in the 
middle of a word may result in the insertion of a line break between that 
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part of the word inside the filled range and that part of the word outside 
the range. 

When filling a range or buffer, FILL does the following to each line: 

• Removes any spaces at the beginning of the line 

• Sets the left margin of the line 

• Moves text up to the previous line if it fits 

• Deletes the line if it contains no text 

• Splits the line if it is too long 

FILL sets the line's left margin to the fill left margin unless that line is 
the first line of the buffer or range being filled. In this case, FILL sets the 
line’s left margin to the fill left margin plus the first line indent. However, 
if you are filling a range and the range does not start at the beginning of a 
line, FILL does not change the left margin of that line. 

FILL moves a word up to the previous line if the previous line is in 
the range to be filled and if the word fits on the previous line without 
extending beyond the fill right margin. Before moving the word up, FILL 
appends a space to the end of the previous line if that line ends in a space 
or a text character. It does not append a space if the previous line ends in 
a word separator other than the space character. 

When moving a word up, FILL also moves up any word separators that 
follow the word, even if these word separators extend beyond the fill right 
margin. Fill does not move up any word separator that would cause the 
length of the previous line to exceed the buffer’s maximum record size. If 
the previous line now ends in a space, FILL deletes that space. FILL does 
not delete more than one such space. 

FILL moves any word separators at the beginning of a line up to the 
previous line. It does this even if the word separators will extend beyond 
the fill right margin. 

FILL splits a line into two lines whenever the line contains two or 
more words and one of the words extends beyond the fill right margin. 
FILL splits the line at the first character of the first word that contains 
characters to the right of the fill right margin, unless that word starts at 
the beginning of the line. In this case, FILL does not split the line. 

When operating on a range that does not begin at the first character of a 
line but does begin left of the fill left margin, FILL splits the line at the 
first character of the range. 

FILL places the cursor at the end of the filled text after completing the 
tasks described above. 
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SIGNALED 

ERRORS 

TPU$JNVRANGE 

WARNING 

You specified an invalid range 
enclosure. 


TPU$_TOOFEW 

ERROR 

FILL requires at least one 
argument. 


TPU$_TOOMANY 

ERROR 

FILL accepts no more than five 
arguments. 


TPU$_ARGMISMATCH 

ERROR 

One of the parameters to FILL is 
of the wrong type. 


TPU$_BADMARGINS 

WARNING 

You specified one of the fill 
margins incorrectly. 


TPU$_INVPARAM 

ERROR 

One of the parameters to FILL is 
of the wrong type. 


TPU$_NOTMODIFIABLE 

WARNING 

You cannot fill text in an 
unmodifiable buffer. 


TPU$_NOCACHE 

ERROR 

FILL could not create a new line 




because there was no memory 
allocated for it. 


TPU$_CONTROLC 

ERROR 

FILL terminated because you 
pressed CTRL/C. 


EXAMPLES 

Q FILL (current_buffer) 

This statement fills the current bufifer. It uses the buffer’s left and right 
margins for the fill left and right margins. The space character is the only 
word separator. Upon completion, the current buffer contains no blank 
lines. All lines begin with a word. Unless the buffer contains a word 
too long to fit between the left and right margins, all text is between the 
buffer’s left and right margins. Spaces may appear beyond the buffer’s 
right margin. 

§ FILL (paragraph_range, 5 ^ 55 ^ 5 ) 

If paragraph_range references a range that contains a paragraph, this 
statement fills a paragraph. FILL uses a left margin of 5 and a right 
margin of 65. It indents the first line of the paragraph an additional 
five characters. The space character and the hyphen are the two word 
separators. If the paragraph contains a hyphenated word, FILL breaks 
the word after the hyphen if necessary. 

§ FILL (paragraph_range, 10, 65, -3) 

This example is like the previous one except that FILL unindents the 
first line of the paragraph by three characters. This is useful for filling 
numbered paragraphs. 
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GET_CLIPBOARD 

Reads STRING format data from the clipboard and returns a string containing 
this data. 

FORMAT 

string := GET_CLIPBOARD 

return value 

A string consisting of the data read from the clipboard. Line breaks are 
indicated by a line-feed character (ASCII (10)). 

DESCRIPTION 

DECwindows provides a clipboard that allows you to move data between 
applications. Applications can write to the clipboard to replace previous 
data, and can read from the clipboard to get a copy of existing data. The 
data in the clipboard may be in multiple formats, but all the information 
in the clipboard must be written at the same time. 

VAXTPU provides no clipboard support for applications not written for 
DECwindows. 


SIGNALED 

ERRORS 


TPU$_NEEDTOASSIGN 


ERROR GET_CLIPBOARD must return a 
value. 


TPU$_TOOMANY 

ERROR 

TPU$_CLIPBOARDFAIL 

WARNING 

TPU$_CLIPBOARDLOCKED 

WARNING 

TPU$_CLIPBOARDNODATA 

WARNING 

TPU$_TRUNCATE 

WARNING 

TPU$_STRTOOLARGE 

ERROR 

TPU$_REQUIRESDECW 

ERROR 


Too many arguments passed to 
GET_CLIPBOARD. 

The clipboard has not returned 
any data. 

VAXTPU cannot read from the 
clipboard because some other 
application has locked it. 

There is no string format data in 
the clipboard. 

Characters have been truncated 
because you tried to add text that 
would exceed the maximum line 
length. 

The amount of data in the 
ciipboard exceeds 65,535 
characters. 

You can use GET_CLIPBOARD 
only if you are using DECwindows 
VAXTPU. 
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EXAMPLE 

new_string := 


GET_CLIPBOARD; 

T his statement reads what is currently in the clipboard and assigns it to 
jiewjstring. 
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GET_DEFAULT 



Returns the value of an X resource from the X resources database. 

FORMAT 

{ ftltegfr } == GET_DEFAULT (stringl, string2) 

PARAMETERS 

stringl 

The name of the resource whose value you want GET_DEFAULT to fetch. 
Note that resource names are case sensitive. 

string2 

The class of the resource. Note that resource class names are case 
sensitive. 

return value 

The string equivalent of the resource value or 0 if the specified resource 
is not defined. Note that, if necessary, the application must convert the 
string to the data type appropriate to the resource. 

DESCRIPTION 

GET_DEFAULT is useful for initializing a layered application that uses 
an X defaults file. You can use GET_DEFAULT only in the DECwindows 
environment. 

SIGNALED 

ERRORS 

TPU$JNVPARAM ERROR One of the parameters was 

specified with data of the wrong 
type. 

TPU$_TOOFEW ERROR Too few arguments passed to 

GET_DEFAULT. 

TPU$_TOOMANY ERROR Too many arguments passed to 

GET_DEFAULT. 

TPU$_NEEDT0ASSIGN error GET_DEFAULT must return a 

value. 

TPU$_REQUIRESDECW ERROR You can use GET_DEFAULT only 

if you are using DECwindows 


VAXTPU. 
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EXAMPLE 

PROCEDURE application_module__init 
LOCAL 

keypad_name; 


keypad__name := GET__DEFAULT ("user.keypad”, "User .Keypad") ; 

EDIT (keypad_name, UPPER); ! Convert the returned string to uppercase. 

IF keypad_name <> '0' 

THEN 

CASE keypad_name 

: eve__set_keypad_edt (); 

: eve__set__keypad__noedt (); 

; eve__set_keypad___wps (); 

: eve_set_keypad_nowps () ; 

: eve_set_keypad_numeric (); 

: eve_set__keypad__vtlOO (); 

OUTRANGE] : eve_set_keypad_numeric; ! If user has 

! used invalid value, 
! set the keypad to 
! NUMERIC setting. 

ENDCASE; 

ENDIF; 


"EDT" 

"NOEDT" 

"WPS" 

"NOWPS" 

"NUMERIC" 

"VTIOO" 

[INRANGE, 


ENDPROCEDURE; 

This code fragment shows the portion of a module_init procedure directing 
VAXTPU to fetch the value of a resource from the X resources database. 
For more information on module_init procedures, see Appendix G. 

If you want to create an extension of EVE that enables use of an X defaults 
file to choose a keypad setting, you can use a GET_DEFAULT statement 
in a module_init procedure. 

To provide a value for the GET_DEFAULT statement to fetch, an X 
defaults file would contain an entry similar to the following: 

User.Keypad : EDT 
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GET_GLOBAL_SELECT 

Supplies information about a global selection. 


FORMAT 


' unspecified ' 
string 
integer 
. array 


f PRIMARY 

GET_GLOBAL_SELECT ( ^ SECONDARY 

I selection_name 

selection_property_name) 


PARAMETERS PRIMARY 

A keyword indicating that the layered application is requesting 
information about a property of the primary global selection. 

SECONDARY 

A keyword indicating that the layered application is requesting 
information about a property of the secondary global selection. 

selection_name 

A string identifying the global selection whose property is the subject of 
the layered application’s information request. Specify the selection name 
as a string if the layered application needs information about a selection 
other than the primary or secondary global selection. 

selection^roperty_name 

A string specifying the property whose value the layered application is 
requesting. 


return value 

unspecified A data type indicating that the information requested by the 

layered application was not available. 

string The value of the specified global selection property. The 

return value is of type string if the value of the specified 
global selection property is of type string. 

integer The value of the specified global selection property. The 

return value is of type integer if the value of the specified 
global selection property is of type integer. 

array An array passing information about a global selection 

whose contents describe information that is not of a data 
type supported by VAXTPU. 

VAXTPU does not use or alter the information in the array; 
the application layered on VAXTPU is responsible for 
determining how the information is used, if at all. Since the 
array is used to receive information from other DECwindows 
applications, all applications that exchange information 
whose data type is not supported by VAXTPU must adopt a 
convention on how the information is to be used. 
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The element array {0} contains a string naming the data 
type of the information being passed. For example, if the 
information being passed is a span, the element contains 
the string "SPAN". The element array {1} contains either 
the integer 8, indicating that the information is passed as 
a series of bytes, or the integer 32, indicating that the 
information is passed as a series of longwords. If array {1} 
contains the value 8, the element array {2} contains a 
string and there are no array elements after array {2}. The 
string does not name anything, but rather is a series of 
bytes of information. As mentioned, the meaning and use 
of the information is agreed upon by convention among 
the DECwindows applications. To interpret this string, the 
application can use the SUBSTR built-in to obtain substrings 
one at a time, and the ASCII built-in to convert the data to 
integer format if necessary. For more information about 
using these VAXTPU elements, see the description of the 
SUBSTR and ASCII built-in procedures. 

If array {1} contains the vaiue 32, the element array {2} and 
any subsequent elements contain integers. The number of 
integers in the array is determined by the application which 
responded to the request for information about the giobal 
selection. The interpretation of the data is a convention 
that must be agreed upon by the cooperating application. 

To determine how many longwords are being passed, 
an application can determine the length of the array and 
subtract 2 to allow for elements array {0} and array {1}. 


DESCRIPTION If an owner for the global selection exists, and if the owner provides the 

information requested in a format that VAXTPU can recognize, GET_ 
GLOBAL_SELECT returns the information. 


SIGNALED 

ERRORS 


TPU$_ARGMISMATCH 

ERROR 

Wrong type of data sent to 
GLOBAL_.SELECT. 

TPU$_NEEDTOASSIGN 

ERROR 

GLOBAL__SELECT must return a 
value. 

TPU$JNVPARAM 

ERROR 

One of the parameters was 
specified with data of the wrong 
type. 

TPU$_REQU1RESDECW 

ERROR 

You can use GLOBAL_SELECT 
only If you are using DECwindows 
VAXTPU. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to 
GLOBAL_SELECT. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
GLOBAL_SELECT. 

TPU$_GBLSELOWNER 

WARNING 

VAXTPU owns the global 
selection. 
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TPU$_BADKEY 

WARNING 

You specified an invalid keyword 
as a parameter. 

TPUSJNVGBLSELDATA 

WARNING 

The global selection owner 
provided data that VAXTPU cannot 



process. 

TPU$_NOGBLSELDATA 

WARNING 

The global selection owner has 
indicated that it cannot provide the 
information requested. 

TPU$_NOGBLSELOWNER 

WARNING 

You have requested information 
about an unowned global 
selection. 

TPU$_TIMEOUT 

WARNING 

The global selection owner did not 
respond before the timeout period 
expired. 


EXAMPLE 

string_to_paste := GET_GLOBAL_SELECT (PRIMARY, "STRING"); 

This statement fetches the text in the primary global selection and assigns 
it to the variable stringjto_paste. 

For another example of how to use the GET_GLOBAL_SELECT built-in, 
see Example B-4. 
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GETJNFO 


DESCRIPTION 


Returns information about the current status of the editor. 

For information on how to get a screen display of the status of your editor, see 
the description of the built-in procedure SHOW. 


This description provides general information on the GETJNFO built- 
ins. In this part, you can also find descriptions of individual GETJNFO 
built-ins. The individual GETJNFO built-ins are grouped according to 
the value of their first parameter. For a list of the groups of GETJNFO 
built-ins, see Table 7-2. 

All GETJNFO built-in procedures have the following two characteristics 
in common; 

• They return a value that is the piece of information you have 
requested. 

• They consist of the GETJNFO statement followed by at least two 
parameters, as follows: 

— The first parameter specifies the general topic about which you 
want information. If you want the GETJNFO built-in to return 
information on a given variable, use that variable as the first 
parameter. For example, if you want to know what row contains 
the cursor in a window stored in the variable command_window, 
you would specify the variable commandjjuindow as the first 
parameter. Thus, you would use use the following statement: 

the_row := GET_INFO (command_window, "current_row"); 

Otherwise, the first parameter is a keyword specifying the general 
subject about which GETJNFO is to return information. The valid 
keywords for the first parameter are as follows: 

AERAY 

BUFFER 

COMMAND_LINE 

DEBUG 

DEFINED_KEY 

KEY.MAP 

KEY_MAP_LIST 

mouse_event_keyword 

PROCEDURES 

PROCESS 

SCREEN 

SYSTEM 

WINDOW 

WIDGET 

For a list of valid mouse event keywords, see Table 7-3. 
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Do not confuse a GETJNFO built-in whose first parameter is 
a keyword (such as ARRAY) with a GETJNFO built-in whose 
first parameter is a variable of a given data type, such as array_ 
variable. For example, the built-in GETJNFO (array_variable) 
shows what string constants can be used when the first parameter 
is an array variable, while the built-in GETJNFO (ARRAY) shows 
what can be used when the first parameter is the ke3rword ARRAY 

— The second parameter (a VAXTPU string) specifies the exact piece 
of information you want. 

— The third and subsequent parameters, if necessary, provide 
additional information that VAXTPU uses to identify and return 
the requested value or structure. 

Each GETJNFO built-in in this section shows the possible return values 
for a given combination of the first and second parameters. For example, 
the built-in GETJNFO (any_variable) shows that when you use any 
variable as the first parameter and the string "type" as the second 
parameter, GETJNFO returns a keyword for the data type of the variable. 

Depending upon the kind of information requested, GETJNFO returns 
any one of the following: 

• An array 

• A buffer 

• An integer 

• A keyword 

• A marker 

• A process 

• A range 

• A string 

• A window 

VAXTPU maintains internal lists of the following items: 

• Arrays 

• Array elements 

• Breakpoints 

• Buffers 

• Defined keys 

• Key maps 

• Key map lists 

• Processes 

• Windows 
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You can step through an internally-maintained list by using "first", "next", 
"previous", or "last" as the second parameter to GETJNFO. Note that 
the order in which VAXTPU maintains these lists is private and may 
change in a future version. Do not write code that depends on a list 
being maintained in a particular order. When you write code to search a 
list, remember that VAXTPU keeps only one pointer for each list. If you 
create nested loops that attempt to search the same list, the results are 
unpredictable. For example, suppose that a program intended to search 
two key map lists for common key maps sets up a loop within a loop. The 
outer loop might contain the following statement: 

GET_INFO (KEY_MAP, "previous", name_of_second_key_inap) 

The inn er loop might contain the following statement: 

GET_INFO (KEY_MAP, "next", name_of_first_key_map) 

In VAXTPU, the behavior of such a nested loop is impredictable. 

Unless documented otherwise, the order of the internal list is not defined. 

The S 3 mtax of GETJNFO depends on the kind of information you are 
trying to get. For more information on specific GETJNFO built-ins, see 
the descriptions in this section. GETJNFO built-ins whose first parameter 
is a keyword are grouped separately from GETJNFO built-ins whose first 
parameter is a variable. 


Table 7-2 GETJNFO Built-in Procedures by First Parameter 


Variable 

Keyword 

Any Keyword or Key Name 

GET_INFO (any_variable) 

GET_INFO (ARRAY) 

GET_INFO (any_keyname) 

GETJNFO (array_variable) 

GETJNFO (BUFFER) 

GET_INFO (any_keyword) 

GETJNFO (buffer_variable) 

GETJNFO (COMMANDJINE) 


GET_INFO (integer_variable) 

GETJNFO (DEBUG) 


GET_INFO (marker_variable) 

GETJNFO (DEFINED_KEY) 


GETJNFO (process_variable) 

GET_INFO (KEY_MAP) 


GETJNFO {range_variable) 

GETJNFO (KEY_MAP_LIST) 


GETJNFO (string_variable) 

GET_INFO (mouse_event_keyword) 


GET_INFO {widget_variable) 

GETJNFO (PROCEDURES) 


GETJNFO (window_variable) 

GETJNFO (PROCESS) 

GETJNFO (SCREEN) 

GET.INFO (SYSTEM) 

GETJNFO (WIDGET) 

GETJNFO (WINDOW) 
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SIGNALED 




ERRORS 

TPU$_BADREQUEST 

WARNING 

Request represented by second 
argument is not understood for 
data type of first argument. 



TPU$_BADKEY 

WARNING 

Bad keyword value or 
unrecognized data type is passed 
as the first argument. 


TPU$_NOCURRENTBUF 

WARNING 

Current buffer is not defined. 


TPU$_NOKEYMAP 

WARNING 

Key map is not defined. 


TPU$_NOKEYMAPLIST 

WARNING 

Key map list is not defined. 


TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong data 
type. 


TPU$_NEEDTOASSIGN 

ERROR 

The GETJNFO built-in can only 
be used on the right-hand side of 
an assignment statement. 


TPU$_NOBREAKPOINT 

WARNING 

This String constant is valid only 
after a breakpoint. 


TPU$_NONAMES 

WARNING 

There are no names matching the 
one requested. 


TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 




GETJNFO built-in. 


TPU$_TOOMANY 

ERROR 

Too many arguments passed to 




the GETJNFO built-in. 


TPU$_UNKKEYWORD 

ERROR 

An unknown keyword has been 
used as an argument. 

EXAMPLES 




Q my_buffer : 

:= GET_INFO (BUFFERS, "current"); 




This assignment statement stores the pointer to the current buffer in the 
variable my_buffer. 

s my_string := GET_INFO (my_buffer, "file_name"); 


This assignment statement stores the name of the input file for my_buffer 
in the variable myjstring. 

g my_buffer := GET_INFO (BUFFERS, "current"); 

This assignment statement stores a reference to the current buffer in the 
variable myjbuffer. 
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Q my_string := GET_INFO (CURRENT_BUFFER, "file__name")/ 

This statement calls the CURRENT_BUFFER built-in, which returns the 
current buffer. The GET JNFO built-in determines the name of the input 
file associated with the current buffer. The input filename is assigned to 
the variable myjstring. 

g is_buf_mod := GET_INFO (CURRENT_BUFFER, "modified"); 

This assignment statement stores the integer 1 or 0 in the variable is_buf_ 
mod, A value of 1 means the current buffer has been modified. A value of 
0 means the current buffer has not been modified. 

g my_window ;= GET_INFO (WINDOWS, "current"); 

length_integer := GET_INFO (my__window, "length", visible_window); 
width_integer := GET_INFO (my__window, "width"); 

These assignment statements store the size of the current window in the 
variables lengthJnteger and widthjnteger, 

g PROCEDURE user_getinfo 

top_of_window := GET_INFO (CURRENT_WINDOW, "top", visible_window); 

! Remove the top five lines from the main window 
ADJUST_WINDOW (CURRENT_WINDOW, +5, 0); 

! Replace removed lines with an example window 
example_window := CREATE__WINDOW (top_of_window, 5, ON); 
example_buffer := CREATE^BUFFER ("EXAMPLE", 

"sys$login:template.txt"); 

MAP (example_window, example_buffer); 

ENDPROCEDURE; 

T his procedure uses GET_INFO to find the top of the current window. 

It then removes the top five lines and replaces them with an example 
window. 

g PROCEDURE user_display_key_map_list 

current__key_map__list := GET__INFO (CURRENT__BUFFER, 

"key_map_list") ; 

MESSAGE (current_key__map_list) ; 

ENDPROCEDURE; 

This procedure retrieves and displays the name of the key map list in the 
current buffer. 

g PROCEDURE show__key_map_lists 
LOCAL key__map__l i s t_name; 

key_map__list_name := GET_INFO (KEY_MAP_LIST, "first"); 

LOOP 

EXITIF key_map_list_name =0; 

SPLIT__LINE; 

COPY_TEXT (key__map__list__name) ; 

key_map_list_name GET__INFO (KEY_MAP__LIST, "next"); 

ENDLOOP; 

ENDPROCEDURE; 


This procedure displays all the key map lists. 
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IQ PROCEDURE show_self_insert 
LOCAL key__map_l i s t_name; 

}cey_map_list_name := GET__INFO (CURRENT_BUFFER, "key_map_list") ; 

IF GET_INFO (key_map_list_name/ ”self_insert”) 

THEN 

MESSAGE ("Undefined printable characters will be inserted"); 

ELSE 

MESSAGE ("Undefined printable characters will cause an error"); 

ENDIF; 

ENDPROCEDURE; 

This procedure shows whether the key map list associated with the current 
buffer inserts imdefined printable characters. 

QQ PROCEDURE show_key_maps_in_list (key_map_list_name) 

LOCAL key_map_name; 

key_map__name : = GET_INFO (KEY__MAP , "first", key_map__l i st_name) ; 

LOOP 

EXITIF key_map_name = 0; 

SPLIT_LINE; 

COPY_TEXT (key_inap_name) ; 

key__map_name := GET_INFO (KEY_MAP, "next", key_map_list_name) ; 

ENDLOOP; 

ENDPROCEDURE; 


This procedure displays the key maps in the key map list 
key_map_list_name. 
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GETJNFO (any_keyname) 

Returns a keyword describing the type of key named by any_keyname. 

For general information about using all forms of GETJNFO built-ins, see the 
description of GETJNFO. 


FORMAT 


r keyword | 

\ integer J - 


(any_keyname 



'’key_modifiers" 

”key_type” 




PARAMETERS ''key_modifiers" 

Returns a bit-encoded integer indicating what key modifier or modifiers 
were used to create the VAXTPU key name specified by the parameter 
any_keyname. For more information about the meaning and possible 
values of key modifiers, see the description of the KEY_NAME built-in. 

VAXTPU defines four constants to be used when referring to or testing 
the numericad value of key modifiers. The correspondence between key 
modifiers, defined constants, and bit-encoded integers is as follows: 


Key Modifier 

Constant 

Bit-Encoded Integer 

SHIFT_MODIFIED 

TPU$K_SHIFT_MODIFIED 

1 

CTRL_MODIFIED 

TPU$K_CTRL_MODIFIED 

2 

HELP_MODIFIED 

TPU$K_HELP_MODIFIED 

4 

ALT MODIFIED 

TPU$K ALT MODIFIED 

8 


Note that the keyword SHIFT_KEY may have been used to create a 
VAXTPU key name. SHIFT_KEY is not a modifier, it is a prefix. The 
SHIFT key, also called the GOLD key by the EVE editor, is pressed and 
released before any other key is pressed. In DECwindows, modi^ng keys 
such as the CTRL key are pressed and held down while the modified key 
is pressed. 

Note, too, that if more than one key modifier was used with the KEY_ 
NAlME built-in, the value of the returned integer is the sum of the integer 
representations of the key modifiers. For example, if you create a key 
name using the modifiers HELP_MODIFIED and ALT_MODIFIED, the 
built-in GETJNFO (key_name, "key_modifiers") returns the integer 12. 

"key_type" 

Returns a kesrword describing the type of key named by anyjteyname. The 
ke 5 Words that can be returned are PRINTING, KEYPAD, FUNCTION, 
SHIFT.KEY, KEYPAD, SHIFT_FUNCTION, and SHIFT.CONTROL. 
Returns 0 if parameterl is not a valid key name. Note that there are 
cases in which GETJNFO (any_keyname, "name") returns the keyword 
PRINTING but the key described by the keyname is not associated with 
a printable character. For example, if you use the KEY_NAME built-in 
to define a key name as the combination of the character A and the ALT 
modifier, and if you then use GETJNFO (any_ke 3 mame, "name") to find 
out how VAXTPU classifies the key, the GETJNFO built-in returns the 
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kejword PRINTING. However, if you use the ASCII built-in to obtedn the 
string representation of the key, the ASCII built-in returns a null string 
because ALT/A is not printable. 


EXAMPLE 

new_key := KEY_NAME (KP4, SHIFT_MODIFIED, CTRL_MODIFIED); 
modifier_value := GET__INFO (new_key, "key_modifiers"); 

MESSAGE (STR (modifier_value)) ; ~ 

IF GET__INFO (new_key, "key_modifiers") 

THEN 

the_name := GET_INFO (new_key, "name") 

MESSAGE (STR (the_name)); 

ENDIF; 

The first statement in the preceding code creates a VAXTPU key name 
for the key sequence produced by pressing the CTRL key, the SHIFT 
key, and the 4 key on the keypad all at once. The new key name is 
assigned to the variable newjtey. The second statement fetches the 
integer equivalent of this combination of key modifiers. The third 
statement displays the integer 3 in the message buffer. The IF clause 
of the fourth statement shows how to test whether a key name was 
created using a modifier. (Note, however, that this statement does not 
detect whether a key name was created using the keyword SHIFT_ 
KEY.) The THEN clause shows how to fetch the key modifier keyword 
or ke 3 words used to create a key name. The final statement displays the 
string KEY.NAME (KP4, SHIFT_MODIFIED, CTRL.MODIFIED) in the 
message buffer. 
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GETJNFO (any_keyword) 



Returns the string representation of the keyword specified in the first 
parameter to GETJNFO. 

For general information about using all forms of GETJNFO built-ins, see the 
description of GET_INFO. See also the description of GETJNFO (integer_ 
variable). 

FORMAT 

string := GETJNFO (keyword, "name") 

PARAMETERS 

keyword 

Returns a VAXTPU keyword whose string equivalent you want GETJNFO 
to return. 

You can use GETJNFO (keyword, "name") to obtain the string equivalent 
of a key name. This is useful for displaying screen messages about keys. 
For example, to obtain the string equivalent of the key name PFl, you 
could use the following statement: 

the_string := GET_INFO (PFl, "name"); 

If a key name is created using several key modifiers, the built-in returns 
the string representations of all the ke 3 nvords used to create the key name. 
For more information on creating key names, see the description of the 
KEYaNAME built-in. 

The following code fragment shows one possible use of GETJNFO 
(keyword_variable, "name"): 

new key := KEY_NAME (KP4, SHIFT_MODIFIED, CTRL_MODIFIED); 

i 

1 


IF GET INFO (new_key, "key_modifiers" ) <> 0 

THEN 

the__name := GET_INFO (new__key, "name") 

ENDIF; 

MESSAGE (STR (the_name)); 

The first statement creates a VAXTPU key name for the key sequence 
produced by pressing the CTRL key, the SHIFT key, and the 4 key on 
the keypad all at once. The new key name is assigned to the variable 
key_name. The IF clause of the statement shows how to test whether 
a key name was created using one or more key modifier keywords. 

(Note, however, that this statement does not detect whether a key 
name was created using the keyword SHIFT_KEY. The built-in GET_ 
INFO (key_name, "key_modifiers") returns 0 even if the key name was 
created using SHIFT_KEY.) The THEN clause shows how to fetch the 
key modifier keyword or keywords used to create a key name. The final 
statement displays the string KEY_NAME (KP4, SHIFT_MODIFIED, 
ALT_MODIFIED) in the message buffer. 

"name" 

Returns the string equivalent of the specified ke 3 rword. 
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GETJNFO (any_variable) 



Returns a keyword specifying the data type of the variable. 

For general information about using all forms of GETJNFO built-ins, see the 
description of GETJNFO. 

FORMAT 

keyword := GETJNFO (any_variable, "type") 

PARAMETERS 

•’type" 

Returns a keyword that is the data type of the variable specified in any__ 
variable. 


EXAMPLE 

IF GET_INFO (select_popup, "type") <> WIDGET 
THEN 

MESSAGE ("Select_popup widget not created.") 

ENDIF; 

The preceding code tests whether the variable select_popup has been 
assigned a widget instance. If not, the code causes a message to be 
displayed on the screen. 
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GETJNFO (ARRAY) 

Returns an array in VAXTPU’s internal list of arrays. 

For generai information about using all forms of GETJNFO built-ins, see the 
description of GETJNFO. 


FORMAT 


array := GETJNFO 


(ARRAY, < 


"current” 

"first" 

"last" 

"next" 

"previous" 






PARAMETERS "current" 

Returns the current array in VAXTPU’s internal list of arrays. You must 
use either GETJNFO (ARRAY, "first") or GETJNFO (ARRAY, "last") 
before you can use GETJNFO (ARRAY, "current"). If you use these built- 
ins in the wrong order or if no arrays have been created, GETJNFO 
(ARRAY, "current") returns 0. 

"first" 

Returns the first array in the VAXTPU internal list of arrays. Returns 0 if 
no arrays are defined. 

"last" 

Returns the last array in the VAXTPU internal list of arrays. Returns 0 if 
no arrays are defined. 

"next" 

Returns the next array in VAXTPU’s internal list of arrays. You must 
use GETJNFO (ARRAY, "first") before you can use GETJNFO (ARRAY, 
"next"). Returns 0 if no arrays are defined. 

"previous" 

Returns the previous array in VAXTPU’s internal list of arrays. You must 
use either GETJNFO (ARRAY, "current") or GETJNFO (ARRAY, "last") 
before you can use GETJNFO (ARRAY, "previous"). If you use these 
built-ins in the wrong order or if no arrays have been created, GETJNFO 
(ARRAY, "previous") returns 0. 
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GETJNFO (array_variable) 

Returns information about a specified array. 

For general information about using ail forms of GETJNFO built-ins, see the 
description of GETJNFO. 


FORMAT 


' array 'j 

buffer 
integer 
keyword 
marker 
< process 
range 
string 
widget 
window 
. unspecified . 


:= GETJNFO 


(array_variable. 


"current" 

"first" 

"highjndex" 
"last" f; 

"lowjndex" 
"next" 

"previous" 


PARAMETERS "current” 

Returns the index value of the current element of the specified array, 
whether the index is of type integer or some other type. Returns any type 
except program, pattern, or learn. Returns the type unspecified if there is 
no current element. 

You must use either GETJNFO (array.variable, "first") or GETJNFO 
(array_variable, "last") before you can use GETJNFO (array_variable, 
"current"). 

••first” 

Returns the index value of the first element of the specified array, whether 
the index is of type integer or some other type. Returns any type except 
program, pattern, or learn. Returns the type unspecified if there is no first 
element. 

••highjndex^^ 

Returns an integer that is the highest valid integer index for the static 
predeclared portion of the array. If the GETJNFO call returns a high 
index lower than the low index, the array has no static portion. 

lasr 

Returns the index value of the last element of the specified array, whether 
the index is of type integer or some other type. Returns any type except 
program, pattern, or learn. Returns the type unspecified if there is no last 
element. 

7oiy_/nc/ex" 

Returns an integer that is the lowest valid integer index for the static 
predeclared portion of the array. If the GETJNFO call returns a high 
index lower than the low index, the array has no static portion. 
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"next" 

Returns the index value of the next element of the specified array, whether 
the index is of type integer or some other type. Returns any type except 
program, pattern, or learn. Returns the type unspecified if there is no next 
element. 

You must use GETJNFO (array_variable, "first") before you can use 
GETJNFO (array_variable, "next"). 

"previous" 

Returns the index value of the previous element of the specified array, 
whether the index is of type integer or some other type. Returns any type 
except program, pattern, or learn. Returns the type unspecified if there is 
no previous element. 

You must use either GETJNFO (array_variable, "current") or GETJNFO 
(array_variable, "last") before you can use GETJNFO (array_variable, 
"previous"). 
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GETJNFO (BUFFER) 

Returns a buffer in VAXTPU’s internal list of buffers. 

For general information about using all forms of GETJNFO built-ins, see the 
description of GETJNFO. 


FORMAT 


buffer := GETJNFO 


(BUFFERISJ < 


"current" 

"erase_unmodifiable" 
"find_buffer", buffer_name 
"first" 

"last" 

"next" 

"previous" 




PARAMETERS "current” 

Returns the current buffer in VAXTPlTs internal list of buffers. Returns 0 
if there is no current buffer. 

GETJNFO (BUFFER|[S]1, "current") always returns the current 
buffer, regardless of whether or you have first used GETJNFO 
(BUFFERtSl, "first") or GETJNFO (BUFFERISI, "last"). Thus, GET_ 
INFO (BUFFERISJ), "current") is equivalent to the built-in CURRENT. 
BUFFER. 

"erase_unmodifiable " 

Returns 1 if unmodifiable records can be erased from the specified buffer 
and returns 0 if the records cannot be erased. 

"findjbuffer" 

Returns the buffer whose name you specify (as a string) as the third 
parameter. Returns 0 if no buffer with the name you specify is found. 

"first" 

Returns the first buffer in VAXTPU’s internal list of buffers. Returns 0 if 
there is none. 

"last" 

Returns the last buffer in VAXTPU’s interned list of buffers. Returns 0 if 
there is none. 

"next" 

The next buffer in VAXTPU’s internal list of buffers. Returns 0 if there 
are no more. 

"previous" 

Returns the preceding buffer in VAXTPtTs internal list of buffers. Returns 
0 if there is none. 
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GETJNFO (buffer_variable) 

Returns information about a specified buffer. 

For generai information about using aii forms of GETJNFO buiit-ins, see the 
description of GETJNFO. 


FORMAT 


< 


integer 

keyword 

learn_sequence 

marker » 

program 

range 

string 


:= GETJNFO 


' ”before_bor 
"beyondjeob" 
”beyond_eor 
"bound" 

"character" 

"direction" 

"eobjtext" 

"erasejunmodiiiabie" 

"file_name" 

"firstjmarker" 

"firstjrange" 

"journaiing" 

"journaijiie" 

"journaijname" 

"key_mapjist" 

< "ieft_margin" > 

"left_margin_action" 
"line" 

"mapjcount" 

"maxjines" 

"middiejofjtab" 

"mode" 

"modifiable" 

"modified" 

"name" 

"nextjmarker" 

"next_range" 

"no_write" 

"offset" 

"offset_column" 

. "output_file" 


(buffer_variable, 
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' "permanent” 

"read_routine", GLOBAL_SELECT 
"recordjcount" 

"recordjnumber" 

"recordjsize" 

< "nght_margin" i; 

”right_margin_action" 

"safejorJournaling" 

"system" 

"tab_stops" 

. ”unmodifiable_records" 


"before_bor 

Returns an integer (1 or 0) that indicates whether the editing point is 
located before the be ginnin g of a line. 

"beyondjeob" 

Returns an integer (1 or 0) that indicates whether the editing point is 
located beyond the end of a buffer. 

"beyondjeo!" 

Returns an integer (1 or 0) that indicates whether the editing point is 
located beyond the end of a line. 

"bound" 

Returns an integer (1 or 0) that indicates whether or not the marker 
that is the specified buffer’s editing point is bound to text. For more 
information about bound markers, see Chapter 2. 

"character" 

Returns a string that is the character at the editing point for the buffer. 

"direction" 

Returns the keyword FORWARD or REVERSE. This parameter is 
established or changed with the built-in procedures SET (FORWARD) 
and SET (REVERSE). 

"eobjtext" 

Returns a string representing the end-of-buffer text. This parameter is 
established or changed with the built-in procedure SET (EOBJTEXT). 

''erase_unmodifiable'' 

Returns 1 if unmodifiable records can be erased from the specified buffer 
and returns 0 if the records cannot be erased. 

"fiie_name" 

Returns a string that is the name of a file given as the second parameter 
to CREATE_BUFFER; null if none was specified. 

"first_marker" 

Returns the first marker in VAXTPU’s internal list of markers for the 
buffer. Returns 0 if there is none. You must use GETJNFO (buffer_ 
variable, "first_marker") before the first use of GETJNFO (buffer_ 
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variable, "next_marker"). If you do not follow this rule, GETJNFO 
(buffer_variable, "next_marker") returns 0. 

Note that there is no corresponding "lastjnarker” or "prevjnarker” 
parameter. 

Do not write code that relies on VAXTPU storing markers in one particular 
order. Creating markers or ranges may alter the internal order. In 
addition, the internal ordering may change in future releases. 

"first_range” 

Returns the first range in VAXTPlTs internal list of ranges for the buffer. 
Returns 0 if there are none. You must use GETJNFO (buffer_variable, 
"first_range") before you use GETJNFO (buffer_variable, "next_range") 
or the "next_range" built-in returns 0. 

Note that there is no corresponding "last_range" or ”prev_range" 
parameter. 

Do not write code that relies on VAXTPU storing ranges in one particular 
order. Creating markers or ranges may alter the internal order. In 
addition, the internal ordering may change in future releases. 

"journaling" 

Returns 1 if the specified buffer is being journaled or returns 0 if it is not. 


"journaljfile" 

Returns a string that is the name of the journal file for the specified buffer. 
If the buffer is not being journaled, the call returns 0. 

"journal_name" 

Converts a buffer’s name to a journal file name using the VAXTPU default 
journal file name algorithm. VAXTPU converts the buffer name to a 
journal file name regardless of journaling status. The GETJNFO call does 
not require journaling to be turned on for the specified buffer. For more 
information on this algorithm, see Section 1.7.1. 

"key_map_list" 

Returns a string that is the key map list boimd to the buffer. This 
parameter is established or changed with the built-in procedure SET. 

"Ieft_margin" 

Returns an integer that is the current left margin setting. This parameter 
is established or changed with the built-in procedure SET (LEPT_ 
MARGIN). 

"left_margin_actlon " 

Returns a program or learn sequence specifying what VAXTPU should 
do if the user tries to insert text to the left of the left margin. Returns 
UNSPECIFIED if no left margin action routine has been set. This 
parameter is established or changed with the built-in procedure SET 
(LEFT_MARGIN_ACTION). 

"line" 

Returns a string that is the line of text at the editing point for the buffer. 
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”map_count" 

Returns an integer that is the number of windows associated with the 
buffer. 

''maxjines'' 

Returns an integer that is the maximum number of records (lines) in 
the buffer. This parameter is established or changed with the built-in 
procedure SET. 

"middle_of_tab " 

Returns an integer (1 or 0) that indicates whether the editing point is 
located in the white space within a tab. 

"mode" 

Returns the kesrword INSERT or OVERSTRIKE. This parameter is 
established or changed with the built-in procedures SET (INSERT) and 
SET (OVERSTRIKE). 

"modifiable" 

Returns an integer (1 or 0) that indicates whether the buffer is modifiable. 

"modified" 

Returns an integer (1 or 0) that indicates whether the buffer has been 
modified. 

"name" 

Returns a string that is the name given to the buffer when it was created. 

"next_marker" 

Returns the next marker in VAXTPlPs internal list of markers for the 
buffer. Returns 0 if there are no more. You must use GETJNFO (buffer_ 
variable, "first_marker") before you use GETJNFO (buffer_variable, 
"next_marker") or the "nextjnarker" built-in returns 0. 

Note that there is no corresponding Hastjnarker'' or '^prevjnarker" 
parameter. 

Do not write code that relies on VAXTPU storing markers in one particular 
order. Creating markers or ranges may alter the internal order. In 
addition, the internal ordering may change in future releases. 

"next_range" 

Returns the next range in VAXTPU’s internal list of ranges for the buffer. 
Returns 0 if there are no more. You must use GETJNFO (buffer_variable, 
*'first_range'') before you use GETJNFO (buffer_variable, ''next_range") 
or the ''next_range^' built-in returns 0. 

Note that there is no corresponding '^last_range" or "prev_range" 
parameter. 

Do not write code that relies on VAXTPU storing ranges in one particular 
order. Creating markers or ranges may alter the internal order. In 
addition, the internal ordering may change in future releases. 
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"no_write" 

Returns an integer (1 or 0) that indicates whether the buffer should be 
written to a file at exit time. Note that VAXTPU writes the buffer to a 
file only if the buffer has been modified during the editing session. This 
parameter is established or changed with the built-in procedure SET (NO_ 
WRITE). 

•’Offset" 

Returns an integer that is the niunber of characters between the left 
margin and the editing point. The left margin is coimted as character 
0. A tab is counted as one character, regardless of width. Window shifts 
have no effect on the value returned when you use "offset". The value 
returned has no relation to the visible screen column in which a character 
is displayed. 

"offsetjcotumn" 

Returns an integer that is the screen column in which VAXTPU displays 
the character at the editing point. When calculating this value, VAXTPU 
does not take window shifts into account; VAXTPU assumes that any 
window mapped to the current buffer is not shifted. The value returned 
when you use ''offset ^column" reflects the location of the left margin 
and the width of tabs preceding the editing point. In contrast, the value 
returned when you use ''offset'' is not affected by the location of the left 
margin or the width of tabs. 

”output_file" 

Returns a string that is the name of the file used with the built-in 
procedure SET (OUTPUT_FILE). Returns 0 if there is no output file 
associated with the specified buffer. This parameter is established or 
changed with the built-in procedure SET (OUTPUT_FILE). 

"permanent" 

Returns an integer (1 or 0) that indicates whether the buffer is permanent 
or can be deleted. This parameter is estabhshed or changed with the 
built-in procedure SET (PERMANENT). 

"read_routine" 

This parameter is used with DECwindows only. 

Returns the program or learn sequence that VAXTPU executes when it 
owns a global selection £ind another application has requested information 
about that selection. If the application has not specified a global selection 
read routine, 0 is returned. 

GLOBAL_SELECT is a keyword indicating that the built-in is to return 
the glob 2 d selection read routine. When you use "read_routine" as the 
second parameter to this built-in, you must use the keyword GLOBAL_ 
SELECT as the third parameter, as follows: 

GETJNFO (buffer_variable, "read_routine", GLOBAL_SELECT) 

"record_count" 

Returns an integer that is the number of records (lines) in the buffer. 
Note that GETJNFO (buffer, "record_count") does not count the end-of- 
bufifer text as a record, but GETJNFO (marker, "record_number") does 
if the specified marker is on the end-of-buffer text. Thus, the maximum 
value returned by GETJNFO (buffer, "record_count") is one less than the 
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maximum value returned by GETJNFO (marker, "record_number") if the 
specified marker is on the end-of-buffer text. 

”record_number" 

Returns the record number of the editing point. 

"record_size" 

Returns an integer that is the maximum length for records (lines) in the 
buffer. 

"rightjmargin" 

Returns an integer that is the current right margin setting. This 
parameter is established or changed with the built-in procedure SET 
(RIGHT_MARGIN). 

"right_margin_action " 

Returns a program or learn sequence specifying what VAXTPU should do 
if the user tries to insert text to the right of the right margin. Returns 
TPU$K_UNSPECIFIED if the buffer does not have a right margin action. 

This parameter is established or ch^ulged with the built-in procedure SET 
(RIGHT_MARGIN_ACTION). 

"sa1e_forJournaling” 

Returns 1 if the specified buffer is safe for joumahng or returns 0 if it 
is not. “Safe_forJournaling” means that journaling can be turned on by 
using the SET (JOURNALING) built-in procedure. A buffer is safe for 
journaling if it is empty, has never been modified, or has not been modified 
since the last time it was written to a file. 

"system" 

Returns an integer (1 or 0) that indicates whether the buffer is a system 
buffer. This parameter is established or changed with the built-in 
procedure SET (SYSTEM). 

"tab_stops" 

Returns either an integer or a string. Use the built-in SET (TAB_STOPS) 
to determine the data type of the return value. If you specify a return 
value of type string, the built-in GETJNFO (buffer_variable, "tab_stops") 
returns a string representation of all the column numbers where tab stops 
are set. The column numbers are separated by spaces. If you specify a 
return value of type integer, the return value is the number of coliunns 
between tab stops. 

"unmodifiablejrecords ” 

Returns 1 if the specified buffer contains one or more unmodifiable records. 
The call returns 0 if no unmodifiable records are present in the specified 
buffer. 
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GETJNFO (COMMAND_LINE) 

Returns information about the command line used to invoke VAXTPU. 

For general information about using aii forms of GETJNFO built-ins, see the 
description of GETJNFO. 


FORMAT I |:=GETJNFO (COMMANDJLINE, 

( "character” 

"command" 

"commandJHe" 

"create" 

"display" 

"file_name" 

"initialization" 

"initjiie" 

"initializationjile" 

"journal" 

"journaiJUe" 

"line" 

"modify" 

"nomodify" 

"output" 

"outputjiie" 

"readjoniy" 

"recover" 

"startjcharacter" 

"start_record" 

"section" 

"section_file" 

"workjiie" 

. "write" 


PARAMETERS "character” 

Returns an integer that is the column number of the character position 
specified by the /START_POSITION command qualifier. This parameter is 
useful in a procedure to determine where VAXTPU should place the cursor 
at startup time. The default is 1 if the /START_POSITION qualifier is not 
specified. This parameter is the same as the "start_character" parameter. 

"command" 

Returns an integer (1 or 0) that indicates whether /COMMAND was 
specified when you invoked VAXTPU. 

"commandJfUe " 

Returns a string that is the command file specification. 
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"create" 

Returns an integer (1 or 0) that indicates whether /CREATE is active 
(either by default or because /CREATE was specified when VAXTPU was 
invoked). 

"display" 

Returns an integer (1 or 0) that indicates whether /DISPLAY or 
/INTERFACE is active (either by default, or because /DISPLAY or 
/INTERFACE was specified when VAXTPU was invoked). 

"file_name" 

Returns a string that is a file specification used as a parameter when the 
user invokes VAXTPU. 

"initialization" 

Returns an integer (1 or 0) that indicates whether /INITIALIZATION is 
active (either by default or because /INITIALIZATION was specified when 
VAXTPU was invoked). 

"initjiie" 

Returns a string that is a file specification for /INITIALIZATION. This is a 
synonym for GETJNFO (COMMAND_LINE, "initiahzation_file"). 

"initiaiizationjile" 

Returns a string that is the initialization file specification for 
/INITIALIZATION. 

"journal" 

Returns an integer (1 or 0) that indicates whether /JOURNAL is active 
(either by default or because /JOURNAL was specified when VAXTPU was 
invoked). 

"journaijile" 

Returns a string that is the journal file specification for /JOURNAL. 

"line" 

Returns an integer that is the record number of the line specified by the 
/START_POSITION command qualifier. This parameter is useful in a 
procedure to determine where VAXTPU should place the cursor at startup 
time. The default is 1 if the /START_POSITION qualifier is not specified. 
This parameter is the same as the "start_record'' parameter. 

"modify" 

Returns an integer (1 or 0) that indicates whether the quahfier /MODIFY 
was specified when VAXTPU was invoked by the user or by another 
program. 

"nomodify" 

Returns an integer (1 or 0) that indicates whether the qualifier 
/NOMODIFY was specified when VAXTPU was invoked by the user or 
by another program. 

"output" 

Returns an integer (1 or 0) that indicates whether /OUTPUT is active 
(either by default or because /OUTPUT was specified when VAXTPU was 
invoked). 


7-177 








GETJNFO Built-Ins Grouped by First Parameter 

GETJNFO (COMMAND_UNE) 


"output_file” 

Returns a string that is the output file specification for /OUTPUT. 

"readjonly" 

Returns an integer (1 or 0) that indicates whether /READ_ONLY was 
specified when VAXTPU was invoked. For more information on this call, 
see Chapter 5. 

"recover" 

Returns an integer (1 or 0) that indicates whether /RECOVER was 
specified when VAXTPU was invoked. 

"startjcharacter" 

Returns an integer that is the column number of the character position 
specified by the /START_POSITION command qualifier. This parameter is 
useful in a procedure to determine where VAXTPU should place the cursor 
at startup time. The default is 1 if the /START_POSITION qualifier is not 
specified. 

This parameter is a S 3 monym for "character”. 

"start_record" 

Returns an integer that is the record number of the line specified by the 
/START_POSITION command qualifier. This parameter is useful in a 
procedure to determine where VAXTPU should place the cursor at startup 
time. The default is 1 if the /START_POSITION qualifier is not specified. 
This parameter is a synon 3 mi for "line". 

"section" 

Returns an integer (1 or 0) that indicates whether /SECTION is active 
(either by default or because /SECTION was specified when VAXTPU was 
invoked). 

"section_file" 

Returns a string that is the section file specification for /SECTION. 

"work_file" 

Returns a string that is the work file specification for /WORK 

"write" 

Returns an integer (1 or 0) that indicates whether /WRITE was specified 
when VAXTPU was invoked. For more information on this statement, see 
Chapter 5. 
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GETJNFO (DEBUG) 

Returns information about the status of a debugging session using the 
VAXTPU Debugger. 

For general information about using all forms of GETJNFO built-ins, see the 
description of GETJNFO. 


FORMAT 




string 

contents 

integer 

parameter 

string 

variabie 


»:= GETJNFO (DEBUG, 


' "breakpoint" 

"examine", variabie_name 
"iine_number" 

"iocai" 

"next" 

"parameter" 

"previous" 

, "procedure" 


PARAMETERS "breakpoint" 

Returns a string that is the neime of the first breakpoint. This estabUshes 
a breakpoint context for the “next” and “previous” parameters. TPU$_ 
NONAMES is returned if there are no breakpoints. 

"examine" 

Returns the contents of the specified variable. TPU$_NONAMES is 
returned if the specified variable cannot be found. 

You must specify a string containing the name of the variable as the third 
parameter to GETJNFO (DEBUG, "examine"). 

"iine_number" 

Returns an integer that is the line number of the breakpoint within the 
procedure. If the procedure is unnamed, 0 is returned. 

"iocai" 

Returns the first local variable in the procedure. This establishes a context 
for the “next” and “previous” parameters. TPU$_NONAMES is returned if 
there are no local variables. 
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"next" 

Returns the next parameter, local variable, or breakpoint. Before using 
GETJNFO (DEBUG, "next"), you must first use one of the following 
built-ins: 

• GETJNFO (DEBUG, "local”) 

• GETJNFO (DEBUG, "breakpoint") 

• GETJNFO (DEBUG, "parameter") 

TPU$_NONAMES is returned if there are no more. 

"parameter" 

Returns the first parameter of the procedure. GETJNFO (DEBUG, 
"parameter") causes the VAXTPU Debugger to construct a list of all the 
formal parameters of the procedure you are debugging. Once this Ust is 
constructed, you can use GETJNFO (DEBUG, "next") and GETJNFO 
(DEBUG, "previous"). VAXTPU signals TPU$_NONAMES if the procedure 
you are debugging does not have any parameters. 

"previous" 

Returns the previous parameter, local variable, or breakpoint. TPU$_ 
NONAMES is returned if there are no more. 

"procedure" 

Returns a string that is the name of the procedure containing the 
breakpoint. The null string is returned if the procedure has no name. 
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GETJNFO (DEFINED_KEY) 


Returns a keyword that is the key name of a specified key. GETJNFO 
(DEFINED_KEY) takes a string as a third parameter. The string specifies the 
name of either the key map or key map list to be searched. 

Note that “current” is not valid when the first parameter is DEFINED_KEY or 
KEY_MAP, aithough it is valid when the first parameter is KEY_MAP_LIST. 

For generai information about using aii forms of GETJNFO buiit-ins, see the 
description of GETJNFO. 


FORMAT 


keyword := GETJNFO 


(DEFINED_KEY, < 


"first” 

"last" 

"next" 

"previous" 


> , namejstring) 


PARAMETERS "first" 

Returns a keyword that is the key name of the first key in the specified 
key map or key map list. 

"last" 

Returns a keyword that is the key name of the last key in the specified 
key map or key map list. 

"nexf" 

Returns a ke 3 rword that is the key name of the next key in the specified 
key map or key map list. Returns 0 if last. Use string constant ""firsf 
before using ''next/' 

"previous" 

Returns a keyword that is the key name of the previous key in the 
specified key map or key map list. Returns 0 if first. Use “last” before 
using “previous.” 
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GETJNFO (integer_variable) 



Returns the string representation of any integer that is an equivalent of a 
keyword. 

For general information about using all forms of GETJNFO built-ins, see 
the description of GETJNFO. See also the description of GETJNFO (any_ 
keyword). 

FORMAT 

string := GETJNFO (integer, "name”) 

PARAMETERS 

integer 

Returns an integer that is the equivalent of a VAXTPU ke 3 nvord. When 
you use GETJNFO (integer, "name"), the built-in returns the string 
representation of the ke 5 rword that is equivalent to the specified integer. 

For example, the following statement assigns the string object to the 
variable equiv_string: 

equiv_string := GET_INFO (10, "name"); 

(The value 14 is the integer equivalent of the keyword PROCESS.) 

Note that you should not use the integer equivalents of keywords in 
VAXTPU code. Digital does not guarantee that the existing equivalences 
between integers and keywords wfil always remain the same. 

"name" 

Returns the string equivedent of the specified integer or ke 3 rword. 
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GETJNFO (KEY_MAP) 


Returns information about a key map in a specified key map list. GET_INFO 
(KEY_MAP) takes a string as a third parameter. The string specifies the name 
of the key map list to be searched. 

Note that “current" is not valid when the first parameter is DEFINED_KEY or 
KEY_MAP, although it is valid when the first parameter is KEY_MAP_LIST. 

For general information about using all forms of GETJNFO built-ins, see the 
description of GETJNFO. 


FORMAT 


r string 1 
\ integer / 


GETJNFO (KEY_MAP, 


"first" 

"last" 

"next" 

"previous" 


> , namejstring ) 


PARAMETERS "first” 

Returns a string that is the name of the first key map in the key map hst. 
Returns 0 if there is none. 

"last" 

Returns a string that is the name of the last key map in the key map list. 
Returns 0 if there is none. 

"next" 

Returns a string that is the name of the next key map in the key map list. 
Returns 0 if there is none. Use string constant “firsts before using “next.” 

"previous" 

Returns a string that is the name of the previous key map in the key map 
list. Returns 0 if there is none. Use “last” before using “previous.” 
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GETJNFO (KEY_MAP_LIST) 


Returns information about a key map list. 

Note that “current" is not valid when the first parameter is DEFINED_KEY or 
KEY_MAP, although it is valid when the first parameter is KEY_MAP_LIST. 

For general information about using all forms of GETJNFO bullt-lns, see the 
description of GETJNFO. 


FORMAT 



(KEY_MAP_LIST, < 


"current" ' 
"first" 

"last" J ) 
"next" 

"previous" . 


PARAMETERS "currenV 

Returns a string that is the name of the current key map list. Returns 0 if 
there is none. 

’•first” 

Returns a string that is the name of the first key map list. Returns 0 if 
there is none. 

•’last" 

Returns a string that is the name of the last key map list. Returns 0 if 
there is none. 

’’next” 

Returns a string that is the name of the next key map list. Returns 0 if 
there is none. Use string constants “current” or “first” before using “next.” 

’’previous” 

Returns a string that is the name of the previous key map list. Returns 0 
if there is none. Use “current” or “last” before using “previous.” 
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GETJNFO (marker_variable) 

Returns information about a specified marker. 

For general information about using all forms of GETJNFO built-ins, see the 
description of GETJNFO. 


FORMAT ( buffer 1 

< integer > := GETJNFO (marker_variable, 
[ keyword J 

r "before_bor 
''beyond_eob” 

"beyondjeo!” 

"bound" 

"buffer" 

"display_value" 

"left_margin" 

< "middle_of_tab" >) 

"offset" 

"offset_column" 

"record_number" 

"rightjmargin" 

"unmodifiable_records ” 

"video" 

. "within_range", range 


PARAMETERS "befOK_bor 

Returns 1 if the specified marker is located before the beginning of a line; 
returns 0 if it is not. 

"beyond_eob" 

Returns 1 if the specified marker is located beyond the end of a buffer; 
returns 0 if it is not. 

"beyond_eor 

Returns 1 if the specified marker is located beyond the end of a line; 
returns 0 if it is not. 

"bound" 

Returns 1 if the specified marker is attached to a character; returns 0 if 
the marker is free. For more information on bound and free markers, see 
Section 2.6. 

"buffer" 

Returns the buffer in which the marker is located. 
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’'display_value" 

Returns the display value of the record in which the specified marker is 
located. For more information about display values, see the descriptions of 
the SET (DISPLAY.VALUE) and SET (RECORD.ATTRIBUTES) built-in 
procedures. 

”left_margin" 

Returns an integer that is the current left margin setting of the line 
containing the marker. 

"middle_of_tab " 

Returns an integer (1 or 0) that indicates whether the marker is located in 
the white space created by a tab. 

•’Offset" 

Returns an integer that is the number of characters between the left 
margin and the marker. The left margin is counted as character 0. A tab 
is counted as one character, regardless of width. Window shifts have no 
effect on the value returned when you use ""offset’" The value returned has 
no relation to the visible screen column in which the character bound to 
the marker is displayed. 

"offset_column " 

Returns an integer that is the screen column in which VAXTPU displays 
the character to which the marker is bound. When calculating this value, 
VAXTPU does not take window shifts into account; VAXTPU assumes 
that any window mapped to the current buffer is not shifted. The value 
returned when you use ""offset_column” does refiect the location of the left 
margin and the width of tabs preceding the editing point. In contrast, the 
value returned when you use ""offset” is not affected by the location of the 
left margin or the width of tabs. 

"recordjnumber" 

Returns an integer that is the number associated with the record (line) 
containing the specified marker. 

A record number indicates the location of a record in a buffer. Record 
numbers are dynamic; as you add or delete records, VAXTPU changes 
the number associated with a particular record, as appropriate. VAXTPU 
counts each record in a buffer, regardless of whether the line is visible 
in a window or whether the record contains text. Note that GETJNFO 
(marker, "record_number") coimts the end-of-buffer text as a record if 
the specified marker is on the end-of-buffer text, but GETJNFO (buffer, 
”record_count") never counts the end-of-buffer text as a record. Thus, it 
is possible for the value returned by GETJNFO (buffer, "record_count") 
to be one less than the maximum value returned by GETJNFO (marker, 
"record_number"). 

"right_margin" 

Returns an integer that is the current right margin setting of the line 
containing the marker. 

"unmodifiable_records" 

Returns 1 if the record containing the specified marker is unmodifiable. 
The call returns 0 if the record is modifiable. 
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’•video” 

Returns a keyword that is the video attribute of the marker. Returns 0 if 
the marker is a free marker. 

'•within_range” 

Returns an integer (1 or 0) that indicates whether the marker is in the 
range specified by the third parameter. 
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GETJNFO (mouse_event_keyword) 

Returns information about a mouse event. A mouse_event_keyword is a 
keyword representing a single click, multiple click, upstroke, downstroke, or 
drag of a mouse button. For a list of the valid mouse event keywords that you 
can use for the first parameter, see Table 7-3. 

For general information about using all forms of GETJNFO built-ins, see the 
description of GETJNFO. 


FORMAT 


r integer 
I window 


}:= GETJNFO 


(mousejeventjkeyword, 


f "mousejjutton” 
\ "window" 




PARAMETERS 


"mouse_button” 

Returns an integer that is the number of the mouse button specified with 
a mouse event ke 5 rword. 

Table 7-3 lists the valid keywords for the first parameter when you use 
"mousejbutton" as the second parameter. 

Table 7-3 VAXTPU Keywords Representing Mouse Events 


M1UP 

M2UP 

M3UP 

M4UP 

M5UP 

MIDOWN 

M2DOWN 

M3DOWN 

M4DOWN 

M5DOWN 

M1DRAG 

M2DRAG 

M3DRAG 

M4DRAG 

M5DRAG 

Ml CLICK 

M2CLICK 

M3CLICK 

M4CLICK 

M5CLICK 

M1CLICK2 

M2CLICK2 

M3CLICK2 

M4CLICK2 

M5CLICK2 

Ml CLICKS 

M2CLICK3 

M3CLICK3 

M4CLICK3 

M5CLICK3 

M1CLICK4 

M2CLICK4 

M3CLICK4 

M4CLICK4 

M5CLICK4 

M1 CLICKS 

M2CLICK5 

M3CLICK5 

M4CLICK5 

M5CLICK5 


"window" 

Returns the window in which the down stroke occurred that started the 
current drag operation. Returns 0 if no drag operation is in progress for 
the specified mouse button when the built-in is executed. 


The valid keywords for the first parameter when you use "window" as the 
second parameter are MIDOWN, M2DOWN, M3DOWN, M4DOWN, and 


M5DOWN. 
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EXAMPLES 

Q X := GET_INFO (M3CLICK2, ”mouse_button"); 

This statement causes VAXTPU to assign the value 3 to the variable x, 

g the_key := READ_KEY; 

IF GET_INFO (the_key, "mouse_button'') = 3 
THEN 

MESSAGE ("MB3 has no effect in this context."); 

These statements test whether you have pressed MBS and, if so, display a 
message in the message window. 

g PROCEDURE sample_ml_drag 

LOCAL the_window, 
new_window, 
column, 
row, 
temp; 

the_window := GET_INFO (MIDOWN, "window"); 

IF the_window = 0 
THEN 

RETURN (FALSE) 

ENDIF; 

LOCATE_MOUSE (new_window, column, row); 

IF the_window <> new_window 
THEN 

MESSAGE ("Invalid drag of pointer across window boundaries."); 

ENDIF; 

ENDPROCEDURE; 

This procedure, when bound to MIDRAG, responds to a drag event by 
checMng whether you have dragged the mouse across window boimdaries. 
If you have, the procedure displays a message. If not, the procedure 
creates a select range. 
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GETJNFO (PROCEDURES) 



Returns information about a specified procedure. GET_INFO 
(PROCEDURES) takes a string as a third parameter. The string specifies 
the name of the procedure about which you are requesting information. 

For general information about using all forms of GETJNFO built-ins, see the 
description of GETJNFO. 

FORMAT 

( "defined" 'j 

integer := GETJNFO (PROCEDURES, < "minimumjparameters" >, 

\ "maximumjjarameters" ] 

string) 

PARAMETERS 

’•defined’’ 

Returns an integer (1 or 0) that indicates whether the specified procedure 
is user defined. 

’’minimum_parameters” 

Returns an integer that is the minimum number of parameters required 
for the specified user-defined procedure. 

’’maximum_parameters” 

Returns an integer that is the maximum number of parameters required 
for the specified user-defined procedure. 

string 

A string that is the name of the procedure about which you want 
information. 
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GETJNFO (PROCESS) 


Returns a specified process in VAXTPU’s internal list of processes. 

For general information about using all forms of GETJNFO built-ins, see the 
description of GETJNFO. 


FORMAT 


process := GETJNFO 


(PROCESS, < 


"current" ' 
"first" 

"last" >) 

"next" 

"previous" > 


PARAMETERS "currenV 

Returns the current process in VAXTPU’s intem 2 il list of processes. You 
can only use GETJNFO (PROCESS, "current") after you have used GET_ 
INFO (PROCESS, "first") or GETJNFO (PROCESS, "last"). The built-in 
returns 0 if you do not use these GETJNFO built-ins in the correct order. 

"first" 

Returns the first process in VAXTPtTs internal list of processes. Returns 0 
if there is none. 

"last" 

Returns the last process in VAXTPU’s internal list of processes. Returns 0 
if there is none. 

"nexf" 

Returns the next process in VAXTPU’s internal list of processes. Returns 
0 if there are no more processes. Use "first" before using "next", 

"previous" 

Returns the preceding process in VAXTPU’s internal list of processes. 
Returns 0 if there is no previous process. Use "last" before using 
"previous". 
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GETJNFO (process_variable) 



Returns information about a specified process. 

For general information about using all forms of GETJNFO built-ins, see the 
description of GETJNFO. 

FORMAT 


PARAMETERS 

"buffer 

Returns the buffer associated with the process. 

"pid" 

Returns an integer that is the process identification ntimber. 
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GETJNFO (range_variable) 



Returns information about a specified range. 

For generai information about using ail forms of GETJNFO buiit-ins, see the 
description of GETJNFO. 

FORMAT 

{keJJ^ord }== GETJNFO (range_variable, 

( "buffer 1 

< "unmodifiable records" 

1 "video" J 

PARAMETERS 

"buffer" 

Returns the buffer in which the range is located. 

"unmodifiable_records" 

Returns 1 if the specified range contains one or more unmodifiable records. 
The call returns 0 if no unmodifiable records are present in the specified 
range. 

"Video" 

Returns a ke 3 rword that is the video attribute of the range. 
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GETJNFO (SCREEN) 


Returns information about the screen. 

For generai information about using aii forms of GETJNFO buiit-ins, see the 
description of GETJNFO. 


FORMAT 


< 


array 

integer 

keyword 

learn_sequence 

PRIMARY 

program 

SECONDARY 

selection_name 

string 


:= GETJNFO (SCREEN, 


' "active_area" 

"ansijcrt" 

''auto_repeat" 

"avo” 

"client_message” 
"client_message_routine" 
”cross_window_bounds" 
”current_column" 

”current_row" 

"dec_crt” 

"dec_crt2” 

"decwindows" 

”detached_action” 

”detached_reason" 

''edit_mode" 

"eightbit" 

"event", GLOBAL_SELECT 
( PRIMARY 

"globaLselect", \ SECONDARY 
I selection_name 


I 


"grab_routine", 

"icon_name" 

"inputjocus" 

"length" 

, "line_editing" 


GLOBAL_SELECT 

INPUT_FOCUS 


} 
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' "mouse” 

"newjength" 

"new_wiclth" 

"oidjength” 

"old_width" 

"originaljength” 

”original_width” 

"promptjength" 

"prompt_row" 

"read_routine”, GLOBAL_SELECT 
"screenjimits” 

"screenjjpdate” 

"scroll” 

"time", GLOBAL_SELECT 

/ GLOBAL_SELECT \ 
ungrab_routine, | input_FOCUS } 

"visiblejength" 

"vk100" 

"vt100” 

"vt200" 

"vt300" 

"width" 


"active_area" 

Returns an array containing information on the location and dimensions 
of the application’s active area. Returns the integer 0 if there is no active 
area. The active area is the region in a window in which VAXTPU ignores 
movements of the pointer cursor for purposes of distinguishing clicks 
from drags. When you press down a mouse button, VAXTPU interprets 
the event as a click if the upstroke occurs in the active area with the 
downstroke. If the upstroke occurs outside the active area, VAXTPU 
interprets the event as a drag operation. 

A VAXTPU layered application can have only one active area at a time, 
even if the apphcation has more than one window visible on the screen. 
An active area is only valid if you are pressing a mouse button. The 
default active area occupies one character cell. By default, the active area 
is located on the character cell pointed to by the pointer cursor. 

For information on mouse button clicks, which are related to the concept 
of an active area, see the XUI Style Guide. 

GETJNFO (SCREEN, "active_area") returns five pieces of information 
about the active area in integer-indexed elements of the returned array. 
You need not use the CREATE_ARRAY built-in before using GETJNFO 
(SCREEN, "active_area"); VAXTPU assigns a properly structured array to 
the return variable you specify. The structure of the array is as follows: 


Array Element Contents 

array {1} The window containing the active area 

array {2} The column forming,the leftmost edge of the active area 
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Array Element 

Contents 

array {3} 
array {4} 
array {5} 

The row forming the top edge of the active area 

The width of the active area, expressed in columns 

The height of the active area, expressed in rows 


"ansLcrt" 

Returns an integer (1 or 0) that indicates whether the terminal is an 
ANSI.CRT. 

”auto_repeat" 

Returns an integer (1 or 0) that indicates whether the terminal’s 
autorepeat featime is on. 

"avo" 

Returns an integer (1 or 0) that indicates whether the ADVANCED_ 
VIDEO attribute has been set for the terminal. 

"dientjmessage" 

Returns a keyword indicating whether VAXTPU has received a KILL_ 
SELECTION client message or a STUFF_SELECTION client message. If 
the call is used when there is no current client message, the integer 0 is 
retimied. 

GETJNFO (SCREEN, "client_message") is used in a VAXTPU-layered or 
EVE-layered application’s client message routine. This routine provides 
the application’s response to a client message received from another 
application. 

GETJNFO (SCREEN, "client_message") returns the ke:^ord KILL_ 
SELECTION when the user is copying from an application layered on 
VAXTPU or on EVE that owns the input focus to another application. 

To do so, the user selects text in the VAXTPU/EVE-layered application. 
This designates the text to be placed in the primary global selection when 
another application asks to read the selection. Next, the user clicks the 
MB3 button in the other appUcation. This causes the text in the primary 
global selection to be copied at the location indicated by the pointer when 
the user clicked on MBS. If the user uses CTRL/MBS to copy the selection 
into the other application, this means that after the selection is copied 
into the other application, it is deleted from the VAXTPU/EVE-layered 
application. In this case, after the other application inserts the text from 
the primary global selection, that application sends a KILL_SELECTION 
client message to the VAXTPU/EVE-layered application. When the 
VAXTPU/EVE-layered application detects that a client message has been 
received, it executes its client message routine. This routine contains a 
statement using GETJNFO (SCREEN, ”client_message"). In the case 
described here, the return value is the keyword KILL_SELEC'nON. The 
VAXTPU/EVE-layered application then deletes the selected text. 

GETJNFO (SCREEN, "client_message") returns the kejrword STUFF_ 
SELECTION when the user is copying from some application into the 
VAXTPU/EVE-layered application that owns the input focus. The user 
performs a drag operation using the MBS button to select the text in 
the other application. The application grabs ownership of the secondary 
global selection and assigns to it the selected text. The application then 
sends a STUFF_SELECTION client message to the VAXTPU/EVE-layered 
application. When the VAXTPU/EVE-layered application detects that a 
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client message has been received, it executes its client message routine. 
This routine contains a statement using GETJNFO (SCREEN, "client, 
message"). In the case described here, the return value is the keyword 
STUFF.SELECTION. The VAXTPU/EVE-layered application then inserts 
the text from the secondary global selection at the VAXTPU/EVE-layered 
application’s editing point. 

”client_message_routine " 

Returns the program or learn sequence designated as an application’s 
client message action routine. Returns 0 if none is designated. 

”cross_window_bounds" 

Returns an integer (1 or 0) that indicates whether the CURSOR_ 
VERTICAL built-in causes the cursor to cross a window boundary if 
the cursor is at the top or bottom of the window. 

”current_column " 

Returns an integer that is the number of the current column. 

"current_row” 

Returns an integer that is the number of the current row. 

"dec_crf 

Returns an integer (1 or 0) that indicates whether the terminal is a DEC_ 
CRT. For more information on this terminal characteristic, see the SET 
TERMINAL command in the VMS DCL Dictionary. 

"dec_crt2" 

Returns an integer (1 or 0) that indicates whether the terminal is a DEC_ 
CRT2. For more infonnation on this terminal characteristic, see the SET 
TERMINAL command in the VMS DCL Dictionary. 

"decwindows" 

Returns 1 if your system is running the DECwindows version of VAXTPU, 
otherwise returns 0. For more information about the DECwindows version 
of VAXTPU, see Chapter 1. 

"detachedjaction " 

Returns the current detached action routine. If no such routine is 
designated, returns the type UNSPECIFIED. 

"detached_reason " 

Returns a bit-encoded integer indicating which of the five possible 
detached states the cursor is in. 

Digital recommends that you use the VAXTPU predefined constants rather 
than the actual integers to refer to the reasons for detachment. Table 7-4 
shows the correspondence of constants, integers, and reasons. 
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Table 7-4 Detached Cursor Flag Constants 


Constant 

Value 

Reason 

TPU$K_OFF_LEFT 

1 

The editing point is off the left side of the current 
window. 

TPU$K_OFF_RIGHT 

2 

The editing point is off the right side of the current 
window. 

TPUSKJNVISIBLE 

4 

The editing point Is on a record that is invisible in 
the current window. 

TPU$K_DISJOINT 

8 

The current buffer is not mapped to the current 
window. 

TPU$K_UNMAPPED 

16 

No current window exists. 


Note that it is possible for TPU$K_INVISIBLE to be set in combination 
with either the TPU$K_OFF_LEFT or TPU$K_OFF_RIGHT flags. 

"edit_mode” 

Returns an integer (1 or 0) that indicates whether the terminal is set to 
edit mode. 

"eightbir 

Returns an integer (1 or 0) that indicates whether the terminal uses 8-bit 
characters. 

"event” 

This parameter is used with DECwindows only. 

When you use "event" as the second parameter, you must specify the 
keyword GLOBAL_SELECT as the third parameter. GLOBAL_SELECT 
indicates that GETJNFO is to supply information about a global selection. 

If called from within a global selection grab or ungrab routine, GETJNFO 
(SCREEN, "event", GLOBAL_SELECT) identifles the global selection that 
was grabbed or lost. GETJNFO (SCREEN, "event", GLOBAL_SELECT) 
returns a keyword if the global selection was the primary or secondary 
selection. The built-in returns a string naming the global selection if 
the grab or ungrab involves a global selection other than the primary or 
secondary selection. 

If called from within a routine that responds to requests for information 
about a global selection, GETJNFO (SCREEN, "event", GLOBAL_ 
SELECT) returns an array. The array contains the information an 
application needs to respond to the request for information about the 
global selection. The array contEiins the following information: 

array {1} The keyword PRIMARY, the keyword SECONDARY, or a string. This 

element identifies the global selection about which information was 
requested. 

array {2} A string. This element identifies the global selection property about 

which information has been requested. 

The GETJNFO (SCREEN, "event") built-in returns 0 if the built-in is not 
responding to a grab, an ungrab, or a selection information request. 
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For more information about grabbing and ungrabbing a global selection, 
see the VMS DECwindows Guide to Application Programming, 

"global_select" 

This parameter is used with DECwindows only. 

Returns the integer 1 if VAXTPU currently owns the specified global 
selection; 0 if it does not. 

You must specify one of the following parameters as a third parameter to 
GETJNFO (SCREEN, "global_select"): 

PRIMARY A keyword directing VAXTPU to get information on the 

primary global selection. 

SECONDARY A keyword directing VAXTPU to get information on the 

secondary giobal selection. 

selection_name A string identifying the global selection about which 

VAXTPU is to get information. 

For more information about grabbing and ungrabbing a global selection, 
see the VMS DECwindows Guide to Application Programming. 

”grab_routine" 

This parameter is used with DECwindows only. 

Returns the program or learn sequence designated as the apphcation’s 
global selection or input focus grab routine. Returns the integer 0 if the 
requested grab routine is not present. 

You must specify one of the following keywords as a third parameter to 
GETJNFO (SCREEN, "grab_routine"): 

GLOBAL_SELECT A keyword indicating that GETJNFO is to return the global 
selection grab routine. 

INPUT_FOCUS A keyword indicating that GETJNFO is to return the input 

focus grab routine. 

Icon^name'" 

This parameter is used with DECwindows only. 

Returns the string used as the layered apphcation’s name in the 
DECwindows icon box. 

"inputjfocus" 

This parameter is used with DECwindows only. 

Returns an integer (1 or 0) indicating whether VAXTPU currently owns 
the input focus. Input focus is the ability to process user input from the 
keyboard. 

"length" 

Returns an integer that is the current length of the screen (in rows). 

"Unejediting" 

Returns an integer (1 or 0) indicating whether the line-editing terminal 
attribute is turned on. On a character-cell terminal, returns 1 if the 
line-editing terminal attribute is turned on, otherwise returns 0. In 
DECwindows VAXTPU, this parameter always returns 0. 
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"mouse” 

Returns an integer (1 or 0) that indicates whether VAXTPU’s mouse 
support capability is turned on. 

"new_length" 

This parameter is used with DECwindows only. 

Returns an integer that is the length (in rows) of the screen after the 
resize action routine is executed. 

Resize action routines should use the length returned by GETJNFO 
(SCREEN, "newjength") to determine the length of their windows. If it is 
used outside a resize action routine, this length is the same as the current 
length of the screen. 

"new_width" 

This parameter is used with DECwindows only. 

Returns an integer that is the width (in columns) of the screen after the 
resize action routine is executed. 

Resize action routines should use the length returned by GETJNFO 
(SCREEN, "new_width") to determine the width of their windows. If it is 
used outside a resize action routine, this width is the same as the current 
width of the screen. 

"oidjength" 

This parameter is used with DECwindows only. 

Returns an integer that is the length (in rows) of the screen before the 
most recent resize event. 

The "old_length" value is initially set to the length of the screen at startup. 
T his value is reset after VAXTPU processes a resize event and before 
VAXTPU executes the resize action routine. 

"old_width" 

This parameter is used with DECwindows only. 

Returns the width (in columns) of the screen before the most recent resize 
event. 

The "oldjjuidth" value is initially set to the width of the screen at startup. 
This value is reset after VAXTPU processes a resize event and before 
VAXTPU executes the resize action routine. 

"originaljength " 

Returns an integer that is the number of lines the screen had when 
VAXTPU was invoked. 

"origmal_width " 

Returns an integer that is the width of the screen when VAXTPU was 
invoked. 

"promptjength " 

Returns an integer that is the number of lines in the prompt area. 
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"prompt_row" 

Returns axi integer that is the screen line number at which the prompt 
area begins. 

"read_routine" 

This parameter is used with DECwindows only. 

Returns the program or learn sequence that VAXTPU executes when it 
owns a global selection and another application has requested information 
about that selection. If the application has not specified a global selection 
read routine, 0 is returned. 

You must specify the ke3word GLOBAL_SELECT as the third parameter 
to GETJNFO (SCREEN, "read.routine"). GLOBAL_SELECT indicates 
that GETJNFO is to return the global selection read routine. 

"screenjimits" 

Returns an integer-indexed array specifying the minimiun and maximum 
screen length and width. 

An integer-indexed array uses four elements to specify the minimum and 
maximum screen width and length. The array indices and the contents of 
their corresponding elements are as follows. 


Array 

Element 

Contents 

array {1} 

The minimum screen width, in columns. This value must be at least 

0 and less than or equal to the maximum screen width. The default 
value is 0. 

array {2} 

The minimum screen length, in lines. This value must be at least 0 
and less than or equal to the maximum screen length. The default 
value is 0. 

array {3} 

The maximum screen width, in columns. This value must be greater 
than or equal to the minimum screen width and less than or equal to 
255. The default value Is 255. 

array {4} 

The maximum screen length, in lines. This value must be greater 
than or equal to the minimum screen length and less than or equal 
to 255. The default value is 255. 


"screen_update " 

Returns an integer (1 or 0) that indicates whether screen updating is 
turned on. 

"scroll" 

Returns an integer (1 or 0) that indicates whether the terminal has 
scrolling regions. For more information on scrolling regions, see the 
description of the built-in SET (SCROLLING). 
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"time" 

This parameter is used with DECwindows only. 

Returns a string in VMS delta time format indicating the amount of time 
after requesting global selection information that VAXTPU waits for a 
reply. When the time has expired, VAXTPU assumes the request will not 
be answered. 

You must specify the keyword GLOBAL_SELECT as the third parameter 
to GETJNFO (SCREEN, "time"). 

"ungrab_routme " 

This parameter is used with DECwindows only. 

Returns the program or learn sequence that VAXTPU executes when it 
loses ownership of a global selection or of the input focus. Returns 0 if the 
requested ungrab routine is not present. 

You must specify one of the following kesrwords as a third parameter to 
GETJNFO (SCREEN, "ungrab.routine"); 

GLOBAL_SELECT A keyword indicating that GETJNFO is to return the global 
selection ungrab routine 

INPUT_FOCUS A keyword indicating that GETJNFO is to return the input 

focus ungrab routine 

"visiblejength" 

Returns an integer that is the page length of the terminal. 

"vklOO" 

Returns an integer (1 or 0) that indicates whether the terminal is a 
GIGI.TM 

"vtlOO" 

Returns an integer (1 or 0) that indicates whether the terminal is in the 
VTIOO series. 

"vt200" 

Returns an integer (1 or 0) that indicates whether the terminal is in the 
VT200 series. 

"vt300" 

Returns an integer (1 or 0) that indicates whether the terminal is in the 
VT300 series. 


"width" 

Returns an integer that is the current physical width of the screen. 
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GETJNFO (string_variable) 

Returns information about the specified string. The string must be the name 
of a keymap or keymap list. 

For general information about using all forms of GETJNFO built-ins, see the 
description of GET_INFO. 


FORMAT ( integer \ 

< keyword > := GETJNFO (string_variable, 

[ program j 

' "journal" 

"pre_keyjorocedure" 
"post_keyjprocedure" I , 
^ "selfjnsert" r 

"shift_key" 

. "undefinedjkey" 


PARAMETERS "Journal" 

Returns an array containing information about the buffer change journal 
file whose name you specify with the string parameter. If the specified file 
is not a journal file, the integer 0 is returned. 

The array indices and the contents of the corresponding elements of the 
returned array are as follows: 


Index Contents of Element 


1 The name of the buffer whose contents were journaled. 

2 The date and time the journal file was created. 

3 The date and time the edit session started. 

4 The name of the source file. A source file is a file to which the buffer 
has been written. The journal file maintains a pointer to the source 
file. This enables the journal file to retrieve from the source file the 
buffer contents as they were after the last write operation. If the 
buffer has not been written out or if none of the source files will be 
available during recovery, this element contains a null string. 

5 The name of the output file associated with the buffer. This is the file 
name specified with the SET (OUTPUT) built-in. 

6 The name of the original input file associated with the buffer by the 
CREATE__BUFFER built-in. If there is no associated input file or if 
the Input file will not be available during a recovery, this element 
contains a null string. 

7 The Identification string for the version of VAXTPU that wrote the 
journal file. 


Note that all elements are of type string. 
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"pre_key_procedure” 

Returns the program, stored in the specified keymap or keymap list, that 
is called before execution of code bound to keys. Returns 0 if no procedure 
was defined by SET (PRE_KEY_PROCEDURE). 

"post_key_procedure” 

Returns the program, stored in the specified kejmaap or keymap list, that 
is called before execution of code bound to keys. Returns 0 if no procedure 
was defined by SET (POST_KEY_PROCEDURE). 


"self insert" 


Returns an integer (1 or 0) that indicates whether printable characters are 
to be inserted into the buffer if they are not defined. This parameter is 
established or changed with the built-in procedure SET (SELF_INSERT). 



"shift_key" 


Returns a keyword that is the key name for the key currently used as 
the shift key. This parsuneter is established or changed with the built-in 
procedure SET (SHIFT_KEY). 


"undefined_key" 


Returns the program that is called when an vmdefined character is 
entered. Returns 0 if the program issues the default message. This 
parameter is established or changed with the built-in procedure SET 
(UNDEFINED_KEY). 
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GETJNFO (SYSTEM) 

Returns information about the system. 

For general information about using all forms of GETJNFO built-ins, see the 
description of GETJNFO. 


FORMAT 


' integer ^ 

keyword 

< learn_sequence > := GETJNFO 
program 

. string j 

( "bell” 


(SYSTEM. 


”column_move_verticaT 

"display" 

"defauitjdirectory" 

"enable_resize" 

”facility_name" 

"informational" 

"journaiingjrequency" 

"journaijile” 

"Hnejnumber" 

"message_action_level" 

"message_action_type" 

< "messagejiags" 
"pad_overstruck_tabs" 
"recover" 

"resize_action" 

"sectionjiie” 

"shift_key" 

"success" 

"timed_message" 

"timer" 

"traceback" 

"update" 

"version" 

. "work_file" 






PARAMETERS ''bell" 

Returns the keyword ALL if the bell is on for all messages. Returns 
the keyword BROADCAST if the bell is on for broadcast messages only. 
Returns 0 if the SET (BELL) feature is off. This parameter is established 
or changed with the built-in procedure SET. 

"column_move_ vertical" 

Returns 1 if the MOVE_VERTICAL built-in is set to keep the cursor in 
the same column as the cursor moves from line to line. Returns 0 if the 
MOVE_VERTICAL built-in preserves the offset, rather than the column 
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position, from line to line. This parameter is established or changed with 
the built-in procedure SET (COLUMN_MOVE_VERTICAL). 

"display" 

Returns 1 if the /DISPLAY qualifier has been specified by the user or by 
default; otherwise, returns 0. 

"default_directory" 

Returns the name of the current default directory. 

"enable_resize" 

Returns 1 if resize operations are enabled, otherwise returns 0. By default, 
resize operations are not enabled. You can turn resizing on or off with the 
built-in SET (ENABLE_RESIZE). 

"facility_name" 

Returns a string that is the current facihty name. This parameter is 
established or changed with the built-in procedure SET (FACILITY_ 
NAME). 

"informational" 

Returns an integer (1 or 0) that indicates whether informational messages 
are displayed. This parameter is established or changed with the built-in 
procedure SET (INFORMATIONAL). 

"journaling_frequency" 

Returns an integer that indicates how frequently records are written to 
the journal file. This parameter is established or changed with the built-in 
procedure SET (JOURNALING). 

"journai_file" 

Returns a string that is the name of the journal file. 

"Unejnumber" 

Returns an integer (1 or 0) that indicates whether VAXTPU displays the 
line number at which an error occurred. This parameter is established or 
changed with the built-in procedure SET (LINE_NUMBER). 

"message_action_lever 

Returns an integer that is the completion status severity level at which 
VAXTPU performs the message action you specify. The valid values, in 
ascending order of severity, are as follows: 1 (success), 3 (informational), 

0 (warning), and 2 (error). This parameter is estabhshed or changed with 
the built-in procedure SET (MESSAGE_ACTION_LEVEL). 

"message_action_type " 

Returns a keyword describing the action to be taken when VAXTPU 
gignalfi an error, warning, or message whose severity level is greater than 
or equal to the level set with SET (MESSAGE_ACTION_LEVEL). The 
possible keywords are NONE, BELL, and REVERSE. This parameter 
is established or changed with the built-in procedure SET (MESSAGE_ 
ACTION_TYPE). 
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"messagejflags " 

Returns an integer that is the current value of the message flag setting. 
This parameter is established or changed with the built-in procedure SET 
(MESSAGE.FLAGS). 

"pad_overstruck_tabs " 

Returns an integer (1 or 0) that indicates whether VAXTPU preserves the 
white space created by a tab character. This parameter is established or 
changed with the built-in procedure SET (PAD_OVERSTRUCK_TABS). 

"recover" 

Returns an integer (1 or 0) that indicates whether a recovery using a 
keystroke journal file is currently in progress. Be careful when using 
this built-in—specifying different VAXTPU actions during a recovery 
than during an ordinary editing session may cause VAXTPU keystroke 
journaling to fail. 

"resizejaction " 

Returns the program or learn sequence designated as the apphcation’s 
resize action routine. Returns 0 if the requested resize action routine 
is not present. You can designate a resize action routine using the SET 
(RESIZE_ACTION) built-in. 

"sectionJfHe" 

Returns a string that is the name of the section file used when the user 
invoked VAXTPU. 

"shiftjkey" 

Returns a keyword that is the value of the current shift key set with SET 
(SHIFT_KEY) for the current buffer. 

"success" 

Returns an integer (1 or 0) that indicates whether success messages are 
displayed. This parameter is established or changed with the built-in 
procedure SET (SUCCESS). 

"timedjmessage " 

Returns a string of text that VAXTPU displays at 1-second intervals in the 
prompt area if the SET (TIMER) feature is on. 

"timer" 

Returns the integer 1 if SET (TIMER) has been enabled, otherwise returns 

0 . 

"traceback" 

Returns an integer (1 or 0) that indicates whether VAXTPU displays the 
call stack for VAXTPU procedures when an error occurs. This parameter 
is established or changed with the built-in procedure SET (TRACEBACK). 
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"update" 

Returns an integer that is the update number of this version of VAKTPU. 

"version" 

Returns an integer that is the version number of VAXTPU. 

"work_file" 

Returns a string that is the name of the work file opened during startup. 
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GETJNFO (WIDGET) 

Returns information about VAXTPU widgets in generai or about a specific 
widget whose name you do not know at the time you use the buiit-in. 

The GETJNFO (WIDGET) buiit-in is used with DECwindows oniy. 

For generai information about using all forms of GETJNFO built-ins, see the 
description of GET_iNFO. 


FORMAT 


integer 

widget get INFO (WIDGET, 
array ( - \ 

NONE 

^ "callbackjparameters”, array 

■children-. [ }, array 

^ "menujposition", mouse_down_button 

■WC©9( »-, ( , 

t I SCREEN, widget_name 


} 




PARAMETERS "ca/lbackjparameters” 

Returns the widget instance performing the callback, the closure value 
associated with the widget instance, and the reason for the callback. Note 
that in DECwindows documentation, the closure is called the tag. 

array An array used to return values for the callback, the closure, and the 

reason. The array has the following indices of type string: "widget”, 
"closure", and "reason__code". GET_INFO (WIDGET, "callback^ 
parameters") places the corresponding values in the array elements. 
VAXTPU automatically creates the array In which the return values 
are placed. 

To use this parameter, specify a variable that has been declared 
or initialized before you use it. The initial type and value of the 
variable are unimportant. When GETJNFO (WIDGET, "callback^ 
parameters") places the return values in the array, the Initial values 
are lost. 

Note that the integer on the left side of the assignment operator 
indicates whether GET__INFO was used correctly. 

GETJNFO (WIDGET, "callback__parameters") should be used in a 
widget callback procedure. If you use this built-in outside a widget 
callback procedure, the value returned is indeterminate. If you 
use the built-in inside a widget callback procedure and callback 
information is available, the built-in returns 1. 

For more information about callbacks and closure values In 
DECwindows VAXTPU, see Chapter 4. For general information 
about using callbacks and closure values, see the VMS DECwindows 
Guide to Application Programming. 
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’’children'’ 

Returns the number of widget children controlled by the specified widget. 
The array parameter returns the children themselves. If the keyword 
SCREEN is specified instead of a widget, the built-in returns the number 
of children controlled by the VAXTPU main window widget. 

’’menujposition” 

Returns information about any pop-up widgets that are set for menu 
positioning when you press the specified mouse button. If no pop-up 
widgets are set, returns the keyword NONE; otherwise, returns an 
integer-indexed array of all pop-ups set for menu positioning. 

mouse_down_button This keyword (MIDOWN, M2DOWN, M3DOWN, 

M4DOWN, or M5DOWN) indicates the mouse button 
associated with the pop-up menus. 

’’widgetjd” 

Returns the widget instance whose name matches the specified widget 
name. The remaining parameters are as follows: 

The widget that is an ancestor of the widget instance 
returned by the GETJNFO (WIDGET) built-in. 

A keyword indicating that VAXTPU’s main window widget 
is the ancestor of the widget instance that you want the 
GETJNFO (WIDGET) built-in to return. 

A string that is the fully qualified name of the widget 
you want the built-in to return. To specify this parameter 
correctly, start the string with the name of the widget’s 
parent. Use the same name you used to specify the parent_ 
widget parameter. If you used the SCREEN parameter 
Instead of the parent_widget parameter, start the string with 
the widget name tpu$mainwindow. 

Next, specify the names of the ancestors, if any, that occur 
in the widget hierarchy between the parent and the widget 
itself. Start with the ancestor just below the parent and 
progressively specify more immediate ancestors. Finally, 
specify the name of the widget you want the GETJNFO 
(WIDGET) built-in to return. Separate all widget names with 
periods. 

The fully qualified widget name is case sensitive. 

GETJNFO (WIDGET, "widgetjd") calls the X Toolkit routine NAME TO 
WIDGET. 

For more information on DECwindows concepts such as parent widgets, 
ancestor widgets, and the distinction between widget classes and widget 
instances, see the VMS DECwindows Guide to Application Programming, 


parent_widget 

SCREEN 

widget_name 
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EXAMPLES 

D PROCEDURE eve$callback_ciispatch 

LOCAL the__program, 
status, 
temp_array; 

ON_ERROR 

[TPU$_CONTROLC]: 

eve$$x_state_array {eve$$k_cominand_line_flag} ;= eve$k__invoked__by key; 
eve$learn__abort; ” ~ 

ABORT; 

[OTHERWISE]: 

eve$$x_state__array {eve$$k_command_line_flag} := eve$k invoked by key; 
ENDON_ERROR - - - 

IF NOT eve$x_decwindows___active 
THEN 

RETURN (FALSE); 

ENDIF; 

eve$$x__state_array {eve$$k__command_line__flag} := eve$k_invoked_by_menu; 
status := 

GET_INFO (WIDGET, "callback_parameters", temp_array); ! This statement using 

! GET_INFO (WIDGET) 

! returns the calling 
! widget, the closure, 

! and the reason code. 


! The following statements make the contents of "temp_array" 

! available to all the eve$$widget_xxx procedures 

eve$x_widget := temp_array {"widget"}; 

! This array element contains the widget 
! that called back. 

eve$x_widget__tag ;= temp_array {"closure"}; 

! This array element contains the widget tag 
! that is assigned to the widget in the UIL file. 
eve$x_widget_reason := temp_array {"reason_code"}; 

! This array element contains callback reason code. 

! The next line gets the callback routine from the array indexed 
! by closure values. 

the__program := eve$$x_widget_array {eve$x__widget_tag} ; 

IF the_program <> 0 
THEN 

EXECUTE (the_program); 

ENDIF; 

eve$$x_state_array {eve$$k_command_line_flag} ;= eve$k__invoked by key; 

RETURN; ~ 

ENDPROCEDURE; 

This procedure shows one possible way that a layered apphcation can use 
GETJNFO (WIDGET, "callback_parameters", array). The procedure is a 
simplified version of the EVE procedure EVE$CALLBACK^DISPATCH. 
You can find the origineil version in SYS$EXAMPLES:EVEiMENUS.TPU. 
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(For more information about using the files in SYS$EXAMPLES as 
examples, see Section B.l.) 

This version of EVE$CALLBACK_DISPATCH handles callbacks from EVE 
widgets. The statement GETJNFO (WIDGET, "callback_parameters", 
temp_array) copies the following three items into elements of the array 
tempjxrray: 

• The widget that is calling back 

• The widget’s integer closure 

• The reason why the widget is calling back 

The array eve$$x_widget_array contains pointers to all of EVE’s callback 
routines in elements indexed by the appropriate integer closure values. 
This procedure locates the correct index in the array and executes the 
corresponding callback routine. 

Warning: This simplified version of EVE$C AL i LB ACK_DISPATCH does 
not completely replace the version in existing EVE code. 
Furthermore, Digital does not guarantee that this example will 
work successfully with future versions of EVE. This example 
is presented solely to illustrate how EVE uses the built-in 
GETJNFO (WTOGET, "callback^parameters**, array) in a callback 
handling procedure. 


the_text_widget := GET_INFO (WIDGET, "widget_id”, new_dialog, 

"NEW__DIALOG.NEW__TEXT") ; 

This statement assigns to the variable thejextjuuidget the widget instance 
named by the string NEW_DIALOG.NEW_TEXT, The widget instance is 
the child of the widget instance assigned to the variable newjiialog, 

PROCEDURE eve__show_widgets ! Display the widget hierarchy 

local 

loop_index, 
num_topmost, 
widget_array; 

widget_array := 0; 

num__topmost :=GET_INFO (WIDGET, "children", SCREEN, widget__array) ; 

IF num_topmost > 0 
THEN 

loop_index := 1; 

LOOP 

EXITIF loopjndex > num_topmost; 
show_widget_tree (widget_array, ""); 
loop__index := loopjndex + 1; 

ENDLOOP; 

ENDIF; 

ENDPROCEDURE; 

PROCEDURE show__widget_tree ! Recursively display the widget tree 

(the_array, the_string) 
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LOCAL 

chilci_array, 

highest, 

loop_index, 

nuin_children; 

child___array := 0; 
loop_index := 1; 

highest := get_info (the_array, "high index"); 

LOOP 

EXITIF loop__index > highest; 

MESSAGE (the_string + GET_INFO (the_array {loop_index}, "name") 

+ ASCII (%oll) 

+ GET_INFO (the__array {loop_index}, "class")); 
num_children := GET__INFO (WIDGET, "children", 

the_array {loop_index}, child__array) ; 

IF num_children > 0 
THEN 

show__widget_tree (child_array, the_string + " ") ; 

ENDIF; 

loop_index := loop_index + 1; 

ENDLOOP; 

ENDPROCEDURE; 

This procedure shows how to use GETJNFO (WIDGET, "children") to 
display the entire hierarchy of widgets known to a VAXTPU session. 
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GETJNFO (widget__variable) 

Returns information about a specified widget variabie. 

The GETJNFO (widget_variable) buiit-in is used with DECwindows oniy. 

For generai information about using aii forms of GETJNFO buiit-ins, see the 
description of GETJNFO. 


FORMAT 


integer 

learn_sequence 

program 

string 


► := GETJNFO 


(widget_variable, 


' "callbackjroutine" 

"class" 

"isjmanaged" 

"is_subclass", widget_class 


"name" 

"parent" 

"resources" 

"text" 


( array \ 

"widgetjnfo", | Q^gjjgjri arg_pair... ] J 




PARAMETERS "callback_routine” , 

Returns the program or learn sequence desi^ated as the apphcations 
callback routine for the specified widget. This is the program or learn 
sequence that VAXTPU should execute when a widget callback occurs for 
the specified widget instance. For more information about callbacks, see 
Chapter 4. 

"Class’’ 

Returns the name of the class to which the specified widget instance 
belongs. 

’’isjmanaged’’ 

Returns 1 (TRUE) if the specified widget is managed; otherwise, it 
returns 0 (FALSE). This built-in calls the DECwindows Toolkit routine 
IS MANAGED. 

’’is_subclass’’ 

Returns 1 (TRUE) if the specified widget belongs to the class referred to by 
the specified integer or belongs to a subclass of that class. A TRUE value 
indicates only that the widget is equal to or is a subclass of the specified 
class; the value does not indicate how far down the class hierarchy the 
widget’s class or subclass is. If the widget is not in the class, or one of its 
subclasses, this GETJNFO call returns 0 (FALSE). 
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widget_class The integer specifying the widget class to use in the subclass 

test. This value is returned from the DEFINE_WIDGET_CLASS 
built-in procedure. 

"name" 

Returns a string that is the name of the specified widget instance. 

"parent" 

Returns the parent of the specified widget instance. If the widget has no 
parent, the call returns 0. 

"resources" 

Returns a string-indexed array in which each index is a valid resource 
name for the specified widget. The corresponding array element is a string 
containing the resource’s data type and class, separated by a line feed 
(ASCII (10)). 

"text" 

Returns a string that is the value of the specified simple text widget. (The 
value of a text widget is the text entered into the text widget by the user 
in response to a prompt in a dialog box.) GETJNFO (widget_variable, 
"text") is equivalent to the XUI Tbolkit routine dwt$s_text_get_string. 

If the specified widget is not of class SText, VAXTPU signals the status 
TPU$_WIDMISMATCH. 

"widget_info" 

Returns the current values for one or more resources of the specified 
widget. 

Note that the values are returned in the array or series of argument pairs 
that is passed as the third parameter. The integer on the left side of the 
assignment operator indicates whether the built-in executed successfully. 

The third parameter is either an array or a series of paired arguments, 
specified as follows: 

array Each array index must be a string naming a valid resource 

for the specified widget. Note that resource names are case 
sensitive. The corresponding array element contains the 
value of the resource. The array can contain any number of 
elements. 

argjDair A string naming a valid resource for the widget followed by 

a variable to store the value of the resource. Separate the 
resource name string from the variable with a comma and a 
space, as follows; 


resource_name__string, resource__value 

You can fetch as many resources as you want by using 
multiple pairs of arguments. 

GETJNFO (widget_variable, "widgetjnfo", array, arg_pair) is functionally 
equivalent to the X Tcolkit routine GET VALUES. 

If you specify the name of a resource that the widget does not support, 
VAXTPU signals the error TPU$_ARGMISMATCH. 


7-215 





GETJNFO Built-Ins Grouped by First Parameter 

GETJNFO (widget_variable) 


If the requested resource is a list of items and the list contains no entries, 
the GETJNFO call uses either the element of the array parameter or uses 
the value parameter to return an array containing no elements. 

For more information about specifying resources, see Chapter 4. 


EXAMPLES 

Q EXECUTE (GET_INFO (eve$x__replace_dialog, 

"callback_routine")); 

This statement executes the callback routine for the widget eve$x_replace_ 
dialog. Note that this statement is valid only after the Replace dialog box 
has been used at least once, because EVE does not create any dialog box 
until you have invoked it. 

g PROCEDURE sample__return_naine 
LOCAL status; 

status := GET__INFO (eve$x_replace__dialog, 

"name"); 

MESSAGE ("The data type of status is; "); 

MESSAGE (STR (GET_INFO(status, "type"))); 

MESSAGE ("The value of status is: "); 

MESSAGE (STR (status)); 

ENDPROCEDURE; 

This procedure displays the name of the widget instance specified by the 
variable eve$x_replacejdialog. To confirm that the widget has been created 
as expected, the procedure also displays a message identifying the data 
type of the variable’s contents. Note that the procedure is valid only after 
the Replace dialog box has been used at least once, because EVE does not 
create any dialog box until you have invoked it. 

A statement containing the built-in GETJNFO (widget, "name") can 
be useful in code implementing a debugging command that evaluates 
VAXTPU statements, expressions, and variables. 

g eve$x_needfilename_dialog := CREATE_WIDGET ("NEEDFILENAME_DIALOG", 

eve$k_widget_hierarchy, 

SCREEN, 

eve$kt_callback_routine); 

the_value := "Type filename for writing buffer " + 

get_info (the_buffer, "name"); 

child_of_box ;= get_info (WIDGET, "widget_id", 

eve$x_needfilename_dialog, 

"NEEDFILENAME_DIALOG.NEEDFILENAME_LABEL"); 
status ;= set (WIDGET, child_of_box, eve$dwt$c__nlabel, the__value) ; 

This code fragment creates an EVE file name dialog box widget and 
assigns the widget to the variable eve$xjieedfilenamejdialog. Next, the 
fragment assigns to the variable thejualue a string prompting you for 
the name of a file to which the buffer’s contents should be written. The 
fragment uses the built-in GETJNFO (WIDGET, "widgetjd") to assign 
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the dialog box’s label widget to the variable childjofjbox. Finally, the 
fragment assigns to the label widget’s eve$dwt$cjnlabel resource the 
string contained in thejualue, 

Q PROCEDURE user__widget_replace_all 
CONSTANT 

user__k_widget_name : = "REPLACE_DIALOG. REPLACE__ALL” ; 

LOCAL the_value, 

parent_widget, 
replace_a Unbutton; 

parent__widget := eve$x_replace_dialog; 

replace_all___button := GET_INFO (WIDGET, "widget^id”, 

parent_widget, 
user_k__widget_name) ; 

GET_INFO (replace__all_button, ! This statement uses 

"widget__info", eve$dwt$c_nvalue, ! GET_INFO (widget, "widget_info") 
the_value); • to fetch the value of the 

! dwt$c_nvalue resource. 

IF the_value 
THEN 

MESSAGE ("All instances will be replaced."); 

ELSE 

MESSAGE ("Not all instances will be replaced."); 

ENDIF; 

ENDPROCEDURE; 

This procedure, userjLuidget_replace_all, shows one possible way 
that a layered application can use GETJNFO (widget, "widget_ 
info"). The procedure is a modified version of the EVE procedure 
EVE$$WIDGET_REPIiACE_ALL. You can find the current version in 
SYS$EXAMPLES;EVE$MENUS.TPU. (For more information about using 
the files in SYS$EXAMPLES as examples, see Section B.l.) 

Procedure user_widget_replace_all determines what user message to 
display in response to the EVE command REPLACE. The procedure uses 
GETJNFO (widget, "widgetjnfo") to fetch the value of the resource 
dwt$c_nvalue. A value of 0 means the Replace All toggle button appears 
unshaded while a value of 1 means the toggle button appears solid. 

g temp_array := create array; 

temp_array {"selecteditems" + ascii (10) + "selectedItemsCount") := 0; 
status := get_info (the_widget_id, "widgetjnfo", temp_array) ; 

If the_widget_id is a variable containing a list box widget that has no 
items selected, then 

tempjxrrayCselecteditems" + ascii (10) + "selectedItemsCount") contains 
an empty array when the built-in returns. 
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GETJNFO (WINDOW) 

Returns a window from VAXTPU’s internal list of windows or the current 
window on the screen. 

For general information about using all forms of GETJNFO built-ins, see the 
description of GETJNFO. 


FORMAT 


window := GETJNFO 


(WINDOW[Sl < 


"current" ' 
"first" 

"last" J; 
"next" 

"previous" . 


PARAMETERS "current” , ^ . 

Returns the current window on the screen. Returns 0 if there is none. 
GETJNFO (WINDOWIS]], "current") always returns the current window, 
regardless of whether or you have first used GETJNFO (WINDOW|[S]|, 
"first") or GETJNFO (WINDOWISl, "last"). 

"first” 

Returns the first window in VAXTPU’s internal hst of windows. Returns 0 
if there is none. 

"last" 

Returns the last window in VAXTPU’s internal list of windows. Returns 0 
if there is none. 

"next" 

Returns the next window in VAXTPU’s internal list of windows. Returns 0 
if there are no more windows in the list. Use string constants "current" or 
"first" before using "next". 

"previous" 

Returns the preceding window in VAXTPU’s intemsd list of windows. 
Returns 0 if there are no previous windows in the Ust. Use string 
constants "current" or "last" before using "previous". 
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GETJNFO (window_variable) 


Returns information about a specified window. 

For generai information about using aii forms of GETJNFO buiit-ins, see the 
description of GET_INFO. 


FORMAT 


integer 
buffer 
keyword 
string 
window 
. widget 


:= GETJNFO (window_variable, 


"bottom" 


"before_bol" 

"beyond_eob" 

"beyond_eol" 

"blink_status" 

"blink_video" 

"bold_status" 

"bold_video" 

"bound" 

(T , WINDOW 
TEXT 

VISIBLE_WINDOW 
IL , VISIBLE_TEXT 

"buffer" 

"current_column" 

"current_row" 

"display_value" 

"key_mapjist" 

WINDOW 
TEXT 

VISIBLE_WINDOW 
VISIBLE_TEXT 
(f , WINDOW 
, TEXT 

, VISIBLE_WINDOW 
IL, VISIBLE_TEXT 
"middle_of_tab" 

"next" 

"no_vldeo" 

"no_ videojstatus" 
"orlginal_bottom" 

"originaljength" 

^ "originaljtop" 


"left" 


"length" 
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"right" 


"pad" 

"previous" 

"reversejstatus" 

"reverse_video" 

(f . WINDOW 
, TEXT 

, VISIBLE_WINDOW 
IL , VISIBLE_TEXT 

"scroll" 

"scroll_amount" 

’’onrnll har” / HORIZONTAL \ 
VERTICAL I 

"scroll_bar_auto_thumb'', | 

"scroll_bottom" 

"scroHjtop" 

"shift_amount" 
"special_graphics_status" 
"statusjine" 

"status_video" 

"text" 

WINDOW 
TEXT 

VISIBLE_WINDOW 
li , VISIBLE_TEXT 
"underline_status" 
"underline_video" 

"video" 

"visible" 

"visible_bottom" 

"visiblejength" 

"visiblejtop” 

WINDOW 
TEXT 

VISIBLE_WINDOW 
VISIBLE TEXT 


"top" 


"width" 


PARAMETERS "before_bor 

Returns an integer (1 or 0) that indicates whether the cursor is to the 
left of the current line’s left margin. The return value has no meaning if 
"beyond_eob" is true. This call returns 0 if the window you specified is not 
mapped. 

"beyond_eob" 

Returns an integer (1 or 0) that indicates whether the cursor is below the 
bottom of the buffer. This call returns 0 if the window you specified is not 
mapped. 

"beyondjeo!" 

Returns an integer (1 or 0) that indicates whether the cursor is beyond the 
end of the current line. The return value has no meaning if "beyond_eob"is 
true. This call returns 0 if the window you specified is not mapped. 
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"blinkjstatus" 

Returns an integer (1 or 0) that indicates whether BLINK is one of the 
video attributes of the window’s status line. This parameter is established 
or changed with the built-in procedure SET (STATUS_LINE). 

”blink_video’' 

Returns an integer (1 or 0) that indicates whether BLINK is one of the 
video attributes of the window. This parameter is established or changed 
with the built-in procedure SET (VIDEO). 

"bold_status'’ 

Returns an integer (1 or 0) that indicates whether BOLD is one of the 
video attributes of the window’s status line. This parameter is established 
or changed with the built-in procedure SET (STATUS). 

”bold_video" 

Returns an integer (1 or 0) that indicates whether BOLD is one of the 
video attributes of the window. This par 2 imeter is established or changed 
with the built-in procedure SET (VIDEO). 

''bound” 

Returns £ui integer (1 or 0) that indicates whether the cursor is located on 
a character. 

''bottom'' 

Returns an integer that is the number of the last row or last visible row 
of the specified window, or the specified window’s text area. The window 
row whose number is returned depends on the keyword you specify as the 
third parameter. If you do not specify a keyword, the default is TEXT. 
Valid keywords are as follows: 


Table 7-5 Valid Keywords for the Third Parameter When the Second 
Parameter is "Bottom”, "Left", "Length", "Right", ’Top", or 
"Width" 


Keyword 

Definition 

TEXT 

A keyword directing the built-in to return the specified (left, 
right, top, or bottom) window row or column or the number 
of window rows or columns on which text can be displayed. 
By specifying TEXT instead of VISIBLE__TEXT, you obtain 
information about a window’s rows and columns even if they 
are invisible because the window is occluded. If the window 
is not occluded, the value returned is the same as the value 
returned with VISIBLE__TEXT. 

VISIBLE_TEXT 

A keyword directing the built-in to return the specified (left, 
right, top, or bottom) visible window row or column or the 
number of visible window rows or columns on which text 
can be displayed. When VAXTPU determines a window’s 
last visible text row, VAXTPU does not consider the status 
line or the bottom scroll bar to be a text row. 


(continued on next page) 
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Table 7-5 (Cent.) 

Valid Keywords for the Third Parameter When the 
Second Parameter is "Bottom", "Left", "Length", 
"Right", "Top", or "Width" 

Keyword 

Definition 

VISIBLE_WINDOW 

A keyword directing the built-in to return the specified (left, 
right, top, or bottom) visible window row or column or the 
number of visible window rows or columns in the window. 

WINDOW 

A keyword directing the built-in to return the specified (left, 
right, top, or bottom) window row or column or the number 
of window rows or columns in the window. By specifying 
WINDOW instead of TEXT, you obtain the window’s last 
row or column, even if it cannot contain text because It 
contains a scroll bar or status line. By specifying WINDOW 
Instead of VISIBLE__WINDOW, you obtain information about 
a window’s rows and columns even if they are invisible 
because the window Is occluded. If the window Is not 
occluded, the value returned is the same as the value 
returned with VISIBLE_WINDOW. 


GETJNFO (win(iow_variable, "bottom", TEXT) is a synonym for GET_ 
INFO (window_variable, "origineil_bottom"). The call GETJNFO (window_ 
variable, "bottom", VISIBLE_TEXT) is a synonym for GETJNFO 
(window_variable, "visible_bottom"). 

^•buffer 

Returns the buffer that is associated with the window. Returns 0 if there 
is none. 

"current_column " 

Returns an integer that is the column in which the cursor was most 
recently located. 

"current_row" 

Returns an integer that is the row in which the cursor was most recently 
located. 

”display_value” 

Returns the display value of the specified window. 

"key_map_lisr 

Returns the string that is the name of the key map Ust associated with the 
window you specify. 

left" 

Returns an integer that is the number of the leftmost column or leftmost 
visible column of the specified window, or the specified window’s text 
area. The column whose number is returned depends on the keyword you 
specify as the third parameter. If you do not specify a keyword, the default 
is TEXT. Valid keywords are shown in Table 7-5. 
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"length" 

Returns an integer that is the number of rows or visible rows in the 
specified window or the specified window’s text area. The number of rows 
returned depends on the keyword you specify as the third parameter. If 
you do not specify a keyword, the default is TEXT. Valid keywords are 
shown in Table 7-5. 

"middle_of_tab" 

Returns an integer (1 or 0) that indicates whether the cursor is in the 
middle of a tab. The return value has no meeming if "beyond_eob" is true. 
This call returns 0 if the window you specified is not mapped. 

"next" 

Returns the next window in VAXTPU’s internal list of windows. Retiuns 0 
if there are no more windows in the list. 

"no_video" 

Returns an integer (1 or 0) that indicates whether the video attribute of 
the window is NONE. This parameter is established or changed with the 
built-in procedure SET (VIDEO). 

"no_video_status" 

Returns an integer (1 or 0) that indicates whether the video attribute 
of the window’s status line is NONE. This parameter is estabUshed or 
changed with the built-in procedure SET (STATUS). 

"original_bottom " 

Returns an integer that is the screen line number of the bottom of the 
window when it was created or last adjusted (does not include status fine 
or scroll bar). Digital recommends that you retrieve this information using 
GETJNFO (window, "bottom", text). 

"original_length " 

Returns an integer that is the number of lines in the window when it was 
created. The value returned includes the status line. 

Digital recommends that you retrieve this information using GETJNFO 
(window, "length”, window). 

"originaljtop" 

Returns an integer that is the screen line number of the top of the window 
when it was created. 

"pad" 

Returns an integer (1 or 0) that indicates whether padding blanks have 
been displayed from column 1 to the left margin (if the left margin is 
greater than 1) and from the ends of lines to the right margin. This 
parameter is established or changed with the built-in procedure SET 
(PAD). 

"previous" 

Returns the previous window in VAXTPU’s internal list of windows. 
Returns 0 if there are no previous windows in the list. 
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"reverse_status" 

Returns an integer (1 or 0) that indicates whether REVERSE is one of the 
video attributes of the window’s status line. This parameter is established 
or changed with the built-in procedure SET (STATUS). 

"reverse_video" 

Returns an integer (1 or 0) that indicates whether REVERSE is one of the 
video attributes of the window. This parameter is established or changed 
with the built-in procedure SET (VIDEO). 

"right" 

Returns an integer that is the number of the last column or last visible 
column of the specified window or the specified window’s text area. The 
window column whose number is returned depends on the kejword you 
specify as the third parameter. If you do not specify a keyword, the default 
is TEXT. Valid ke 5 nvords are shown in Table 7-5. 

"scroll" 

Returns an integer (1 or 0) that indicates whether scrolling is enabled for 
the window. This parameter is established or changed with the built-in 
procedure SET (SCROLLING). 

"scroll_amount" 

Returns an integer that is the number of lines to scroll. This parameter is 
established or changed with the built-in procedure SET. 

"scroll_bar" 

This parameter is used with DECwindows only. 

Returns the specified scroll bar widget instance implementing the scroll 
bar associated with a window if it exists, otherwise returns 0. 

You must specify the keyword HORIZONTAL or VERTICAL as the third 
parameter to GETJNFO (window_variable, "scroll_bar"). HORIZONTAL 
directs VAXTPU to return the window’s horizontal scroll bar; VERTICAL 
directs VAXTPU to return the window’s vertical scroll bar. 

"scroll_bar_auto_thumb " 

This parameter is used with DECwindows only. 

Returns an integer (1 or 0) indicating whether automatic adjustment of the 
specified scroll bar slider is enabled. Returns 1 if automatic adjustment is 
enabled, 0 if it is disabled. 

You must specify the keyword HORIZONTAL or VERTICAL as the third 
parameter to GETJNFO (window_variable, "scroll_bar_autoJhumb"). 
HORIZONTAL directs VAXTPU to return information about the window's 
horizontal scroll bar; VERTICAL directs VAXTPU to return information 
about the window's vertical scroll bar. 

"scroUJbottom " 

Returns sm integer that is the bottom of the scrolling area, an offset from 
the bottom screen line. This parameter is established or changed with the 
built-in procedure SET (SCROLLING). 
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’’scroUJtop" 

Returns an integer that is the top of the scrolling area, an offset from the 
top screen line. This parameter is established or changed with the built-in 
procedure SET (SCROLLING). 

”shift_amount" 

Returns an integer that is the number of columns the window is shifted to 
the left. 

"special_graphics_status" 

Returns an integer (1 or 0) that indicates whether SPECIAL_GRAPHICS 
is one of the video attributes of the window’s status line. This parameter is 
estabUshed or changed with the built-in procedure SET (STATUS_LINE). 

*'status_Une'’ 

Returns a string that is the text of the status line. Returns 0 if there is 
none. This parameter is established or changed with the bxiilt-in procedure 
SET (STATUS^LINE). 

"status_video" 

If there is no video attribute or only one video attribute for the window’s 
status line, the appropriate video ke 5 rword (NONE, BLINK, BOLD, 
REVERSE, UNDERLINE or SPECIAL_GRAPHICS) is returned. If there 
are multiple video attributes for the window’s status line, the integer 
1 is returned. If there is no status line for the window, the integer 0 
is returned. This parameter is estabhshed or changed with the built-in 
procedure SET (STATUS_LINE). 

"texf" 

Returns a keyword that indicates which keyword was used with SET 
(TEXT). SET (TEXT) controls text display in a window. SET (TEXT) 
retiums any of the following ke 3 rwords: BLANK_TABS, GRAPHIC_TABS, 
or NO.TRANSLATE. 

"top" 

Returns an integer that is the number of the first row or first visible row 
of the specified window or the specified window’s text area. The window 
row whose number is returned depends on the keyword you specify as the 
third parameter. If you do not specify a keyword, the default is TEXT. 
Valid keywords are shown in Table 7-5. 

"underline_status " 

Returns an integer (1 or 0) that indicates whether UNDERLINE is one 
of the video attributes of the window’s status line. This parameter is 
established or changed with the built-in procedure SET (STATUS__LINE). 

”underline_ video " 

Returns an integer (1 or 0) that indicates whether UNDERLINE is one 
of the video attributes of the window. This parameter is established or 
changed with the built-in procedure SET (VIDEO). 

"video" 

If there is no video attribute or only one video attribute for the window, 
the appropriate video keyword (NONE, BLINK, BOLD, REVERSE, or 
UNDERLINE) is returned. If there are multiple video attributes for the 
window, the integer 1 is returned. If you get the return value 1 and you 
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want to know more about the window’s video attributes, use the specific 
parameters such as "underline_video" and "reverse_video". 

This parameter is established or changed with the built-in procedure SET 
(VIDEO). 

"Visible’’ 

Returns an integer (1 or 0) that indicates whether or not the window is 
mapped to the screen and whether it is occluded. 

"visibiejbottom ’’ 

Returns an integer that is the screen line number of the visible bottom 
of the window (does not include status line). This value can be changed 
using the ADJUST_WINDOW built-in, by creating other windows, or by 
mapping a window. 

Digital recommends that you retrieve this information using GETJNFO 
(window, "bottom", visible_text). 

"visiblejength" 

Returns an integer that is the visible length of the window (includes status 
line). This value differs from the value returned by GET_INFO (window_ 
variable, "originaljength") in that the value returned by "visiblejength" 
is the original length minus the number of window lines (if any) hidden 
by occluding windows. This value can be changed using the ADJUST_ 
WINDOW built-in, by creating other windows, or by mapping a window. 

Digital recommends that you retrieve this information using GETJNFO 
(window, "length", visible_window). 

’’visibiejtop" 

Returns an integer that is the screen line number of the visible top of the 
window. This value can be changed using the ADJUST_WINDOW built-in, 
by creating other windows, or by mapping a window on top of the current 
window. 

Digital recommends that you retrieve this information using GETJNFO 
(window, "top", visible_window). 

"width" 

Returns an integer that is the number of columns or the number of visible 
columns in the specified window or the specified window’s text area. The 
number of columns returned depends on the kejrword you specify as the 
third parameter. If you do not specify a keyword, the default is TEXT. 
Valid keywords are shown in Table 7-5. 

This parameter is established or changed with the built-in procedure SET. 

EXAMPLES 


D last_line ; = 

= GET INFO (bottom window, "bottom", WINDOW); 

This statement returns the last line of the window bottomjwindow. 

The value returned is the line containing the status line or scroll bar, 
whichever comes last, if the window has a status line or scroll bar. For 
another example of code using GETJNFO (window_variable, "bottom", 
WINDOW) see Example B-5. 
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g current_list := GET_INFO (CURRENT_WINDOW, "key_map_list"); 

This statement returns the key map list associated with the current 
window. For an example of code using GETJNFO (window_variable, 
"key_map_list", WINDOW) see Example B-6. 

g first_column := GET_INFO (CURRENT_WINDOW, "left", TEXT); 

This statement returns the leftmost column where text can be displayed 
in the current window. Note that changing the left margin setting has no 
effect on the value returned. 

Q the_length := the_length + GET_INFO (the_window, "length", WINDOW); 

This statement adds the length of the window (the value in the_window) 
to the value in thejength. Note that the length of the window includes 
the length added by the scroll bar and status line, if the window has them. 
For another example of code using GETJNFO (wmdow_variable, "length", 
WINDOW) see Example B-5. 

g last_column := GET_INFO (CURRENT_WINDOW, "right", WINDOW); 

This statement returns the number of the rightmost column in the current 
window. Note that the colmnn whose number is returned can be occupied 
by a vertical scroll bar if one is present. Note, too, that the returned value 
changes if you widen the window, but not if you move the window without 
widening it. 

I first_row ;= GET_INFO (CURRENT_WINDOW, "top", WINDOW); 

This statement returns the number of the first row in the current window. 
Note that the row number returned is relative to the top of the VAXTPU 
screen. Thus, if the current window is not the top window on the VAXTPU 
screen, the row number returned is not 1. For another example of code 
using GETJNFO (window_variable, "top", WINDOW ) see Example B-5. 

B the_width := GET_INFO (CURRENT_WINDOW, "widtli", WINDOW); 

This statement returns the number of columns in the current window. 

For an example of code using GETJNFO (window_variable, "width", 
WINDOW) see Example B-6. 

B the_bar := GET_INFO (CORRENT_WINDOW, "scroll_bar", VERTICAL); 

This statement returns the vertical scroll bar widget associated with the 
current window. For another example of code using GETJNFO (window_ 
variable, "scroll_bar") see Example B-6. 

B status := GET_INFO (CURRENT_WINDOW, 

"scroll_bar_auto_thumb", VERTICAL); 

This statement returns an integer indicating whether automatic 
adjustment is enabled for the vertical scroll bar slider associated with 
the current window. For another example of code using GETJNFO 
(window_variable, "scroll_bar_auto_thumb", WINDOW) see Example B-6. 
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HELP_TEXT 

Invokes the VMS Help Utility. You must specify the help library to be used 
for help information, the initial library topic, the prompting mode for the Help 
Utility, and the buffer to which the help information is to be written. 


FORMAT 

HELP_TEXT (library-file, topic, { } ,buffer) 

PARAMETERS 

library-file 

A string that is the file specification of the help library. 

topic 

A string that is the initial library topic. If this string is empty, the top 
level of help is displayed. 

ON 

A keyword specifying that the Help Utility should prompt the user for 
input. 

OFF 

Specifies that the prompting mode of the Help Utility should be turned off. 

buffer 

The buffer to which the help information is written. 

DESCRIPTION 

You can enter a complete file specification for the help library as the 
first parameter. However, if you enter only a file name, the Help Utility 
provides a default device (SYS$HELP) and default file type (HLB). 

If you do not specify an initial topic as the second parameter, you must 
enter a null string as a place holder. The Help Utility then displays the 
top level of help available in the specified library. 

When the prompting mode is ON for the built-in procedure HELP_TEXT, 
the following prompt appears if the help text contains more than one 
window of information: 

Press RETURN to continue ... 

Before VAXTPU invokes the Help Utility, VAXTPU erases the buffer 
specified as the help buffer. (In EVE the buffer to which the help 
information is written is represented by the variable helpjbuffer.) If 
the help buffer is associated with a window that is mapped to the screen, 
the window is updated each time VAXTPU prompts the user for input. If 
you set the prompting mode to OFF, then the window is not updated by 
the built-in procedure HELP_TEXT. 

If helpjbuffer is not associated with a window that is mapped to the 
screen, the information from the Help Utility is not visible. 
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SIGNALED 

ERRORS 

TPU$_TOOFEW 

ERROR 

The HELP__TEXT built-in requires 
four parameters. 


TPU$_TOOMANY 

ERROR 

You specified more than four 
parameters. 


TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 


TPU$_BADKEY 

ERROR 

Only ON and OFF are allowed. 


TPU$_NOTMODIFIABLE 

WARNING 

The output buffer is currently 
unmodifiable. 


TPU$_SYSERROR 

ERROR 

Error activating the help librarian. 


TPU$_OPENIN 

ERROR 

Error opening help library. 


EXAMPLES 

D HELP_TEXT ("tpuhelp", OFF ,help_buffer) 

This statement causes the top level of help information from the 
SYS$HELP:TPUHELP.HLB library to be written to the help buffer. The 
Help Utility prompting mode is not turned on. 

g HELP_TEXT ("tpuhelp", (READ_LINE ("Topic: ")), OFF, second_buffer) 

This statement prompts the user to provide the topic for the Help Utihty. 
The information on that topic that is in the VAXTPU help library is 
written to secondjbuffer. 

@ ! Interactive HELP 

PROCEDURE user_help 

SET (STATUS_LINE, info_window, UNDERLINE, 

"Press CTRL/Z to leave prompts then CTRL/F to resume editing"); 

MAP (info_window, help_buffer); 

HELP_TEXT ("USERHELP", READ_LINE ("Topic: "), ON, help_buffer); 

ENDPROCEDURE; 

This procedure displays information about getting out of help mode on 
the status line, prompts the user for input, and maps helpjbuffer to the 
screen. 
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INDEX 

Locates a character or a substring within a string and returns its location 
within the string. 

FORMAT 

integer := INDEX (string, substring) 

PARAMETERS 

String 

The string within which you want to find a character or a substring. 

substring 

A character or a substring whose leftmost character location you want to 
find within string 1, 

return value 

An integer showing the character position within a string of the substring 
you specify. 

DESCRIPTION 

The built-in procedure INDEX finds the leftmost occurrence of substring 
within string. It returns an integer that indicates the character position 
in string at which substring was found. If string is not found, VAXTPU 
returns a 0. The character positions within string start at the left with 1. 

SIGNALED 

ERRORS 

TPU$_NEEDTOASSIGN ERROR INDEX must be on the right-hand 

side of an assignment statement. 

TPU$_TOOFEW ERROR INDEX requires two arguments. 

TPU$_TOOMANY ERROR INDEX accepts only two 

arguments. 

TPUSJNVPARAM ERROR The arguments to INDEX must be 

strings. 


EXAMPLES 

Q loc := INDEX ("1234567","67") 

This assignment statement stores an integer value of 6 in the variable loc, 
because the substring "67" is found starting at character position 6 within 
the string "1234567". 
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s 


PROCEDURE user_is__character (c) 
LOCAL symbol__characters; 
symbol__characters : = 


"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"; 


RETURN INDEX( symbol_characters, c ) > 0; 
ENDPROCEDURE; 


This procedure uses the built-in procedure INDEX to return true if a given 
item is an alphanumeric character; otherwise, it returns false. (The list of 
characters in this example does not include characters that are not in the 
ASCII range of the DEC Multinational Character Set. However, you can 
write a procedure using such characters, because VAXTPU supports the 
DEC Multinational Character Set.) The parameter that is passed to this 
procedure is assumed to be a single character. 
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INT 

Converts keyword or a string that consists of numeric characters into an 
integer. 

FORMAT 

1 integerl 'j 

integers := INT ( 1 keyword >) 

[ string 1 integer2 J J 

PARAMETERS 

integerl 

Any integer value. INT accepts a parameter of type integer so you need 
not check the type of the parameter you supply. 

keyword 

A ke 3 rword whose internal value you want. 

string 

A string that consists of numeric characters. 

integer2 

An integer specifying the radix (base) of the string being converted. The 
default radix is 10. The other allowable values are 8 and 16. 

return value 

The integer equivalent of the parameter you specify. 

DESCRIPTION 

You can use INT to store an integer value for a keyword or a string of 
numeric characters in a variable. You can then use the variable name in 
operations that require integer data types. 

INT signals a warning and returns 0 if the string is not a number. 


SIGNALED 

ERRORS 

TPU$_NEEDTOASSIGN 

ERROR 

INT returns a value that must be 
used. 


TPU$_TOOFEW 

ERROR 

INT requires one parameter. 


TPU$_TOOMANY 

ERROR 

INT accepts only one parameter. 


TPU$_ARGMISMATCH 

ERROR 

The parameter to INT was not a 
keyword or string. 


TPU$JNVNUMSTR 

WARNING 

The string you passed to INT was 
not a number. 


TPU$_NULLSTRING 

WARNING 

You passed a string of length 0 to 
INT. 
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TPU$_BADVALUE ERROR You specified a value other than 8, 

10, or 16 for the radix parameter. 


EXAMPLES 

D user_int := INT ("12345") 


This assignment statement converts the string "12345" into an integer 
value and stores it in the variable user int. 


Parameters: 


! new__number New integer value - output 

! promptestring Text of prompt - input 

! no_value_message Message printed if user presses the 

! RETURN key to get out of the command - input 

PROCEDURE user_prompt__number (new__number, prompt_string, 

no_value_message) 

LOCAL read_line_string; 

ON_ERROR 

IF ERROR = TPU$__NULLSTRING 
THEN 

MESSAGE (no_value__message) ; 

ELSE 

IF ERROR = TPU$_INVNUMSTR 
THEN 

MESSAGE (FAO ("Don't understand !AS", 
read_line__string) ) ; 

ELSE 

MESSAGE (ERROR_TEXT); 

ENDIF; 

ENDIF; 

user_prompt_number := 0; 

ENDON_ERROR; 

user_prompt___number := 1; 

read_line_string := READ__LINE (prompt_string)/ 

EDIT (read_line_string, TRIM); 

TRANSLATE (read__line__string, "1", "1"); 

new_number := INT (read_line_string); 

ENDPROCEDURE; 


This procedure is used by commands that prompt for integers. The 
procedure returns true if prompting worked or was not needed; it returns 
false otherwise. The number that is returned is returned in the output 
parameter. 
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JOURNAL CLOSE 



Closes an open keystroke journal file (if one exists for your session) and 
saves the journal file. Note that JOURNAL_CLOSE applies only to keystroke 
journaling. 

FORMAT 

JOURNAL.CLOSE 

PARAMETERS 

None. 

DESCRIPTION 

Once you specify JOURNAL_CLOSE, VAXTPU does not keep a keystroke 
journal of your work until you specify JOURNAL_OPEN. Calling the built- 
in procedure JOURNAJj_OPEN causes VAXTPU to open a new keystroke 
journal file for your session. 

To turn off buffer change journaling, see the description of the SET 
(JOURNALING) built-in procedure. 


Caution: Journal files contain a record of all information being edited. 



Therefore, when editing files containing secure or confidential 
data, be sure to keep the journal files secure as well. 

SIGNALED 

ERROR 

TPU$_TOOMANY ERROR JOURNAL_CLOSE accepts no 

arguments. 


EXAMPLE 


JOURNAL_CLOSE 

This statement causes VAXTPU to close the keystroke journal file, if one 
exists for your editing session. 
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JOURNAL OPEN 



Opens a keystroke journal file and starts making a copy of your editing 
session by recording every keystroke you make. If you invoked VAXTPU with 
the /RECOVER qualifier, then VAXTPU recovers the previous aborted section 
before recording new keystrokes. JOURNAL_OPEN optionally returns a string 
containing the file specification of the file journaled. Note that JOURNAL_ 
OPEN applies only to keystroke journaling. 

FORMAT 

[string := ] JOURNAL.OPEN (file-name) 

PARAMETER 

file-name 

A string that is the name of the keystroke journal file created for your 
editing session. 

return value 

The file specification of the file journaled. 

DESCRIPTION 

VAXTPU saves the keystrokes of your editing session by storing them in 
a buffer. VAXTPU writes the contents of this buffer to the file that you 
specify as a journal file. If for some reason VAXTPU should terminate 
unexpectedly, you can recover your editing session by using this journal 
file. To do this, invoke VAXTPU with the /RECOVER qualifier. See 
Chapter 5 for information on recovering files. 

To turn on buffer change journaling, see the description of the SET 
(JOURNALING) built-in procedure. 

By default, VAXTPU writes keystrokes to the journal file whenever the 
journal buffer contains 500 b 5 d;es of data. VAXTPU also tries to write 
keystrokes to the journal file when it aborts. 

When you recover a VAXTPU session, your terminal characteristics should 
be the same as they were when the journal file was created. If they are 
not the same, VAXTPU informs you what characteristics are different 
and asks whether you want to continue recovering. If you answer yes, 
VAXTPU tries to recover; however, the different terminal settings may 
cause differences between the recovered session and the original session. 

JOURNAL_OPEN succeeds if used in batch mode (NODISPLAY) but 
nothing is journaled as there are no keystrokes in batch mode. 


Caution: Journal files contain a record of all information being edited. 

Therefore, when editing files containing secure or confidential 
data, be sure to keep the journal files secure as well. 
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SIGNALED 

ERRORS 

TPU$_BADJOUFILE 

ERROR 

JOURNAL_OPEN could not open 
the journal file. 


TPU$_TOOFEW 

ERROR 

JOURNAL_OPEN requires one 
argument. 


TPU$_TOOMANY 

ERROR 

JOURNAL_OPEN accepts only 
one argument. 


TPU$JNVPARAM 

ERROR 

The parameter to JOURNAL_ 
OPEN must be a string. 


TPU$_ASYNCACTIVE 

WARNING 

You cannot journal with 
asynchronous handlers declared. 


TPU$_JNLOPEN 

ERROR 

A journal file is already open. 


EXAMPLES 

D JOURNAL__OPEN ("test. f il") 

This statement causes VAXTPU to open a file named TEST.FIL as the 
journal file for your editing session. VAXTPU uses your current default 
device and directory to complete the file specification. 

§ PROCEDURE user__start__journal 
! Default journal name 

! Auxiliary journal name derived from file name 

LOCAL default_journal_name/ 
aux_journal__name; 

IF (GET_INFO (COMMAND_LINE, "journal") = 1) 

AND 

(GET_INFO (COMMAND_LINE, "read_only") <> 1) 

THEN 

aux_journal_name := GET_INFO (CURRENT__BUFFER, "file__name") ; 

IF aux_journal_name = "" 

THEN 

aux_journal_name := GET__INFO (CURRENT_BUFFER, "output__f ile") ; 

ENDIF; 

IF aux_journal_name = 0 
THEN 

aux__journal_name := ""; 

ENDIF; 
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IF aux_journal_name = 

THEN 

default_journal_name ;= "user.TJL"; 

ELSE 

default__journal_name := ".TJL"; 

ENDIF; 

journal_file := GET_INFO (COMMAND_LINE, "journal_file"); 
journal__file := FILE_PARSE (journal_file, default_journal_name, 

aux_journal__name) ; 

JOURNAL__OPEN (journal_file) ; 

ENDIF; 

ENDPROCEDURE; 

This procedure starts journaling. It is called from the TPU$INIT_ 
PROCEDURE after a file is read into the current buffer. 
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KEY NAME 


Returns a VAXTPU keyword for a key or a combination of keys, or creates a 
keyword used as a key name by VAXTPU. 


FORMAT 


keyword2 := KEY_NAME 


{ integer 
key_name 
string 


I 


( SHIFT_KEY 
SHIFT_MODIFIED 
< ALT_MODIFIED 
CTRL_MODIFIED 
I HELP_MODIFIED 


, FUNCTION 
, KEYPAD 


L -li 


PARAMETERS integer 

An integer that is either the integer representation of a ke 5 nvord for a key, 
or is a value between 0 and 255 that VAXTPU interprets as the value of a 
character in the DEC Multinational Character Set. 

key_name 

A keyword that is the VAXTPU name for a key. 

string 

A string that is the value of a key from the main keyboard. 

SHiFT_KEY 

A keyword specifying that the key name created includes one or more 
shift keys. The ke 5 rword SHIFT_KEY specifies the VAXTPU shift key, not 
the key on the keyboard marked SHIFT. The shift key is also referred to 
as the GOLD key in EVE. (See the description of the SET (SHIFT_KEY) 
built-in in the VAX Text Processing Utility Manual.) 

SHIFT_MODiFiED 

A keyword specifying that the key name created by the built-in includes 
the key marked SHIFT on the keyboard. The keyword SHIFT_MODIFIED 
specifies the key that toggles between uppercase and lowercase, not the 
key known as the GOLD key. 

SHIFT_MODIFIED only modifies function keys and keypad keys. 

Digital recommends that you avoid using this keyword in the non- 
DECwindows version of VAXTPU. In non-DECwindows VAXTPU, when 
you create a key name with this keyword, the keyboard cannot generate a 
corresponding key. 

ALTjnODiFiED 

A ke 3 rword specifying that the key name created by the built-in includes 
the ALT key. Note that on most Digital keyboards the ALT key is labeled 
Compose Character. 
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return value 

ALT_MODIFIED only modifies function keys and keypad keys. 

Digital recommends that you avoid using this ke 5 rword in the non- 
DECwindows version of VAXTPU. In non-DECwindows VAXTPU, when 
you create a key name with this keyword, the keyboard cannot generate a 
corresponding key. 

CTRL_MODIFIED 

A keyword specifying that the key name created by the built-in includes 
the CTRL key. 

CTRL_MODIFIED only modifies function keys and ke 3 ^ad keys. 

Digital recommends that you avoid using this keyword in the non- 
DECwindows version of VAXTPU. In non-DECwindows VAXTPU, when 
you create a key name with this keyword, the keyboard cannot generate a 
corresponding key. 

HELP_MODIFIED 

A keyword specifying that the key name created by the built-in includes 
the HELP key. 

HELP_MODIFIED only modifies function keys and keypad keys. 

Digital recommends that you avoid using this keyword in the non- 
DECwindows version of VAXTPU. In non-DECwindows VAXTPU, when 
you create a key name with this ke 3 rword, the keyboard cannot generate a 
corresponding key. 

FUNCTION 

A parameter that specifies that the resulting key name is to be that of a 
function key. 

KEYPAD 

A parameter that specifies that the resulting key name is to be that of a 
ke 3 rpad key. 

A VAXTPU ke 3 rword to be used as the name of a key. 

DESCRIPTION 

Using the KEY_NAME built-in, you can create key names that are 
modified by more than one key. For example, it is possible to create a 
name for a key sequence consisting of the GOLD key, the CTRL key, and 
an alphanumeric or keypad key. 

The built-in GETJNFO (key_name, '’key_modifiers") returns a bit-encoded 
integer whose value represents the key modifier or combination of key 
modifiers used to create a given key name. For more information about 
interpreting the integer returned, see the description of GETJNFO (key_ 
name, "key_modifiers"). 

The built-in GETJNFO (keyword, "name") has been extended to return a 
string including all the key modifier keywords used to create a key name. 
For more information about fetching the string equivalent of a key name, 
see the description of GETJNFO (keyword, "name"). 
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SIGNALED 

ERRORS 

TPU$JNCKWDCOM 

TPU$_MUSTBEONE 

WARNING 

WARNING 

Inconsistent keyword combination. 
String must be one character long. 


TPU$_NOTDEFINABLE 

WARNING 

Second argument is not a valid 
reference to a key. 


TPU$_NEEDTOASSIGN 

ERROR 

KEY_NAME cali must be on the 
right-hand side of an assignment 
statement. 


TPU$_ARGMISMATCH 

ERROR 

Wrong type of data sent to the 
KEY_NAME built-in. 


TPU$_BADKEY 

ERROR 

KEY NAME accepts SHIFT_KEY, 
FUNCTION, or KEYPAD as a 
keyword argument. 


TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
KEY_NAME built-in. 


TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the KEY_NAME built-in. 


EXAMPLES 

D new_key := KEY_NAME (KP4, CTRL_MODIFIED, SHIFT_KEY); 

DEFINE_KEY ("eve_fill", new_key); 

These statements create a name for the key sequence GOLD/CTRLi/KP4 
and bind the EVE command FILL to the resulting key sequence. 

g keyl := KEY_NAME ("Z") 

This assignment statement creates the key name keyl for the keyboard 
key Z. 

g key2 := KEY_NAME (KP5, SHIFT_KEY) 

This example uses KEY_NAME to create a key name for a combination of 
keys. 

Q key3 := KEY_NAME (ASCII (10)) 

This assigiunent statement creates the key name key3 for the line-feed 
character. 

§ ! Procedure to define keys to emulate EDT 

PROCEDURE user_define_edtkey 

! Bind the EDT Fndnxt function to PF3 

DEFINE_KEY ("edt$search_next", PF3); 

! Bind the EDT Find function to SHIFT PF3 

DEFINE_KEY ("edt$search", KEY_NAME (PF3, SHIFT_KEY)); 

ENDPROCEDURE; 

This example shows a portion of a command file that defines the keys for 
an editing interface that emulates EDT. 
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g key4 := KEY_NAME (90) 

This assignment statement creates the key name key4 for the keyboard 
key Z. The key name is identical to keyl in the first example, because 90 is 
the ASCII code for Z. 

B keys := KEY_NAME ("A", KEYPAD) 

This assignment statement creates the key name keyS for the keypad key 
that is terminated by an A in the code that represents key names. This 
is identical to the key name UP, which VAXTPU uses to refer to the up 
arrow key. 

VAXTPU defines a keypad key as a control sequence consisting of the code 
SS3 followed by a character. The control sequence SS3 can be represented 
as follows: 

Esc 0 

For more information on the representation of keys, see the manual for 
your terminal. 

I key6 := KEY_NAME (29, FUNCTION) 

This assignment statement creates the key name key6 for the function 
key whose representation contains the number 29. This is identical to the 
VAXTPU keyword DO, which VAXTPU uses to identify the Do key. 

VAXTPU defines a function key as a control sequence with the following 
format: 

CSI decimal-number ~ 

The element CSI can be represented as follows: 

ESC [ 

In this representation, the decimal number must be m the range 0 to 255. 
For more information on the representation of keys, see the manual for 
your terminal. 
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LAST^KEY 

Returns a VAXTPU keyword for the last key that was entered, read, or 
executed. 

FORMAT 

keyword := LAST_KEY 

PARAMETERS 

None. 

DESCRIPTION 

When VAXTPU is replaying a learn sequence or executing the program 
bound to a key, LAST_KEY returns the last key replayed or processed 
so far, not the last key that was pressed to invoke the learn sequence or 
program. 

When you invoke VAXTPU with the /NODISPLAY qualifier, the value 0 
is returned for LAST_KEY, except in the following case. If you precede 
the LAST.KEY statement with a READ_LINE statement, LAST_KEY 
can return a key name representing the last key read by READ_LINE, 
CTRL/Z, or the RETURN key. See the description of READ_LINE for 
more information on the values that LAST_KEY can return when you use 
LAST_KEY while running VAXTPU in /NO.DISPLAY mode. 

SIGNALED 

ERROR 

TPU$ TOOMANY ERROR Too many arguments passed to 

the LAST_KEY built-in. 


EXAMPLE 

PROCEDURE user_define_key 

def := READ__LINE ("Definition: ")/ 

key := READ_LINE ("Press key to define.",!); 

IF LENGTH (key) > 0 
THEN 

key := KEY_NAME (key) 

ELSE 

key := LAST_KEY; 

ENDIF; 

DEFINE_KEY (def, key); 

ENDPROCEDURE; 

This procedure prompts the user for input for key definitions. 
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LEARN ABORT 



Causes a learn sequence being replayed to be terminated whether or not the 
learn sequence has completed. 

FORMAT 

[integer := ] LEARN.ABORT 

PARAMETERS 

None. 

return value 

An integer indicating whether a leam sequence was actually replaying at 
the time the LEARN_ABORT statement was encoimtered. The vadue 1 is 
returned if a leam sequence was being replayed, 0, otherwise. 

DESCRIPTION 

LEARN_ABORT aborts a leam sequence that is being replayed. Only the 
currently executing leam sequence is aborted. 

Whenever you write a procedure that can be bound to a key, the procedure 
should invoke the LEARN_ABORT built-in in case of error. Using 
LEARN_ABORT prevents a leam sequence from finishing if the leam 
sequence calls the user-written procedure and the procedure is not 
executed successfully. 

SIGNALED 

ERROR 

TPU$_TOOMANY ERROR The LEARN_ABORT built-in takes 

no parameters. 


EXAMPLE 

ON_ERROR 

MESSAGE ("Aborting command because of error.”)/ 

LEARN_ABORT; 

ABORT; 

ENDON_ERROR 

In this error handler, if an error occurs any executing learn sequence is 
aborted. 
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LEARN BEGIN and LEARN END 



Saves all keystrokes typed between LEARN_BEGIN and LEARN_END. 
LEARN_BEGIN starts saving all keystrokes that you type. LEARN_END stops 
the “learn mode” of VAXTPU and returns a learn sequence consisting of ail 
the keystrokes that you entered. 

FORMAT 

LEARN_BEGIN ( | /^q^^xACT 

learn := LEARN_END 

PARAMETERS 

EXACT 

Causes VAXTPU to use the input that was entered for each READ_LINE, 
READ_KEY, or READ_CHAR built-in procedure when the learn sequence 
was created as the input for these built-in procedures when the learn 
sequence is replayed. 

NO_EXACT 

Causes VAXTPU to prompt for new input each time a READ_LINE, 
READ_KEY, or REAb_CHAR built-in procedure is replayed within a learn 
sequence. 

return value 

A variable of type learn storing the keystrokes you specify. 

DESCRIPTION 

You can use the variable name that you assign to a learn sequence as 
the parameter for the built-in procedure EXECUTE to replay a learn 
sequence. You can also use the variable name with the built-in procedure 
DEFINE_KEY to bind the sequence to a key so that the learn sequence is 
executed when you press a key. 

Learn sequences are different from other VAXTPU programs in that 
they are created with keystrokes rather than with VAXTPU statements. 
You create the learn sequence as you are entering text and executing 
VAXTPU commands. Because learn sequences make it easy to collect 
and execute a sequence of VAXTPU commemds, they are convenient for 
creating temporary “programs.” You can replay these learn sequences 
during the eating session in which you create them. 

Learn sequences, created by coUecting keystrokes, are not flexible enough 
to use for writing general programs. Learn sequences are best suited to 
saving a series of editing actions that you perform many times during a 
single editing session. 
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It is possible to save leam sequences from session to session so that you 
can replay them in an editing session other than the one in which you 
created them. To save a leam sequence, bind it to a key; before en^ng 
your editing session, use the built-in procedure SAVE to do an incremental 
save to the section file you are using. Using the built-in procedure SAVE 
causes the new definitions from the current session to be added to the 
section file with which you invoked VAXTPU. For more information, see 
the built-in procedure SAVE. 

VAXTPU key definitions may change in future versions. You may lose 
leam sequences that you have saved when you mn a new version of 


VAXTPU. 


Note: You should not use built-in procedures that can return WARNING 
or ERROR messages as a part of a leam sequence because leam 
sequences do not stop on error conditions. Because the leam 
sequence continues executing after an error or warning condition^ 
the editing actions that are executed after an error or a warning 
may not take effect at the character position you desire. 

If, for example, a built-in procedure SEARCH that you use as a 
part of a leam sequence fails to find the string you specify and 
issues a warning, the leam sequence does not stop executing. This 
can cause the rest of the leam sequence to take inappropriate 
editing actions. 

Pre- and postkey procedures interact with leam sequences in the following 
order: 

1 When the user presses the key or key sequence to which the leam 
sequence is bound, VAXTPU executes the prekey procedure of that key 
if a prekey procedure has been set. 

2 For each key in the leam sequence, VAXTPU executes procedures or 
programs in the following order: 

a. VAXTPU executes the prekey procedure of that key if a prekey 
procedure has been set. 

b. VAXTPU executes the code bound to the key itself. 

C- VAXTPU executes the postkey procedure of that key if a postkey 
procedure has been set. 

3 When all keys in the leam sequence have been processed, VAXTPU 
executes the postkey procedure, if one has been set, for the key to 
which the entire leam sequence was bound. 


SIGNALED 

ERRORS 


TPU$_NOTLEARNING 


WARNING LEARN_BEGIN was not used 

since the last call to LEARN_END. 

WARNING A learn sequence is already in 
progress. 


TPU$_ONELEARN 
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TPU$_TOOFEW 


TPU$_TOOMANY 


TPU$JNVPARAM 


ERROR LEARN_BEGIN requires one 

argument. 

ERROR LEARN__BEGIN accepts only one 

argument. 

ERROR The specified parameter has the 

wrong type. 


EXAMPLE 


LEARN BEGIN (EXACT) 


This represents a typical editing session, 
in which you perform commands that are 
bound to keys. 



do_again := LEARN_END 


This example shows how to combine LEARN_BEGIN and LEAKN_END 
so that all of the keystrokes that you enter between them are saved. The 
ke 5 nvord (EXACT) specifies that if you use READ_LINE, READ_CHAR, 
or READ_KEY within the learn sequence, any input that you enter for 
these built-in procedures is repeated exactly when you replay the learn 
sequence. 
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LENGTH 

Returns an integer that is the number of character positions in a buffer, range, 
or string. 

FORMAT 

( buffer ] 

integer := LENGTH ( < range >) 

[ string J 

PARAMETERS 

buffer 

buffer whose length you want to determine. If you specify a buffer, 
line terminators are not counted as character positions. 

range 

The range whose length you want to determine. If you specify a range, 
line terminators are not coimted as character positions. 

String 

The string whose length you want to determine. 

SIGNALED 

ERRORS 

TPU$_NEEDTOASSIGN ERROR LENGTH must be on the right- 

hand side of an assignment 
Statement. 

TPU$_TOOFEW ERROR LENGTH requires one argument. 

TPU$_TOOMANY ERROR LENGTH accepts only one 

argument. 

TPL)$__ARGMISMATCH ERROR The argument to LENGTH must 

be a String or a range. 

TPLI$__CONTROLC ERROR You pressed CTRL/C while 

LENGTH was executing. 


EXAMPLES 

0 str_len := LENGTH ("Don Quixote") 


§ user_how_long ;= 

This assignment statement stores the number of characters in the string 
"Don Quixote" in the variable str len. In this example, the integer value is 
11. 

= LENGTH (my__range) 

This assignment statement stores the number of character positions 
(excluding line terminators) in my_range in the variable user Jiow Jong, 
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Parameters: 


! mark_j5arameter is user-supplied string, 

! which is used as a mark name 

PROCEDURE user_mark_ (mark__parameter) 

! Local copy of mark_parameter 

LOCAL mark_name; 

ON__ERROR 

MESSAGE (FAO ("Cannot use !AS as a mark name", mark_name)); 
RETURN; 

ENDON__ERROR; 

! 132 - length ("user_mark_") 

IF LENGTH (mark_parameter) > 122 
THEN 

mark_name := SUBSTR (mark_name, 1, 122); 

ELSE 



mark___name := mark_parameter; 


ENDIF; 


EXECUTE ("user_mark__" + mark__name + " := MARK (NONE)"); 
MESSAGE (FAO ("Current position marked as !AS", mark__name)); 
ENDPROCEDURE; 


This procedure puts a marker without any video attributes at the current 
position. The marker is assigned to a variable that begins with user_ 
mark_ and ends with the string you pass as a parameter. The procedure 
writes a message to the message area verifying the mark name that comes 
from the input parameter. 
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LINE.BEGIN 

Matches the beginning of a line. 

FORMAT 

LINE_BEGIN 

PARAMETERS 

None. 

DESCRIPTION 

When used as part of a complex pattern or as an argument to SEARCH, 
LINE_BEGIN matches the start of a line. 

Although LINE__BEGIN behaves much like a built-in, it is actually a 
keyword. 

LINE_BEGIN lets you search for complex strings by creating patterns that 
match certain conditions. For example, if you want to find all occurrences 
of the exclamation point (!) when it is the first character in the line, use 
LINE_BEGIN to create the following pattern: 

pat1 := LINE_BEGIN + 

For more information on patterns, see Chapter 2. 

SIGNALED 

ERROR 

LINE_END is a keyword and has no completion codes. 


EXAMPLES 

D patl := LINE_BEGIN 


This assignment statement stores the beginning-of-line condition in the 
variable patl, 

g POSITION (SEARCH (LINE_BEGIN, REVERSE)); 

This VAXTPU statement positions you at the beginning of the current line. 

S PROCEDURE user_remove_dsrlines 

LOCAL si, 

patl; 

patl := LINE_BEGIN + 

LOOP 

si := SEARCH_QUIETLY (patl, FORWARD); 

EXITIF si = 0; 

POSITION (si); 

ERASE_LINE; 

ENDLOOP; 

ENDPROCEDURE; 
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This procedure removes all DSR commands from a file by searching for a 
pattern that has a period (.) at the beg in n in g of a line and then removing 
the lines that match this condition. 
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LINE_END 

Matches the end of a line. 

FORMAT 

UNE_END 

PARAMETERS 

None. 

DESCRIPTION 

When used as part of a complex pattern or as an argument to SEAECH, 
LINE_END matches the end of a line. 

Although LINE_END behaves much like a built-in, it is actually a 
keyword. 

The end-of-line condition is one character position to the right of the last 
character on a line. 

For more information on patterns, see Chapter 2. 

SIGNALED 

ERROR 

LINE_END is a ke3rword and has no completion codes. 


EXAMPLES 

D patl := LINE_END 

This assignment statement stores the kejnvord LINE_END in the variable 
patl. Patl can be used as an argument to the SEAECH built-in or as part 
of a complex pattern. 

g PROCEDURE user_end_of_line 
LOCAL eol_range; 

eol_range := SEARCH_QUIETLY (LINE_END, FORWARD); 

IF eol_range <> 0 
THEN 

POSITION (eol__range) ; 

ENDIF; 

ENDPROCEDURE; 

If you are not already at the end of the current line, the preceding 
procedure moves the editing point to the end of the line. 
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LOCATE MOUSE 



Locates the window position of the pointer at the time LOCATE_MOUSE is 
invoked. LOCATE_MOUSE returns the window name and the window position 
of the pointer and optionally returns a status indicating whether the pointer 
was found in a window. 

FORMAT 

[ Integer := ] LOCATE_MOUSE (window, xjnteger, yjnteger) 

PARAMETERS 

window 

Returns the window in which the pointer is located. You can pass any data 
type except a constant in this parameter. If the pointer is not found, an 
unspecified data type is returned. 

xjnteger 

Returns the column position of the pointer. You can pass any data 
type except a constant in this parameter. If the pointer is not foimd, 
an unspecified data type is returned. 

yjnteger 

Returns the row position of the pointer. You can pass any data type except 
a constant in this parameter. If the pointer is not found, an unspecified 
data type is returned. This parameter returns 0 if the pointer is in the 
status line for a window. 

return value 

An integer indicating whether the pointer was foimd in a window. The 
value is 1 if VAXTPU finds a window position, 0, otherwise. 

DESCRIPTION 

When the user presses a mouse button, VAXTPU determines the location 
of the mouse pointer and makes that information available while the code 
bound to the mouse button is being processed. Mouse pointer location 
information is not available at any other time. 

In DECwindows VAXTPU, you can use the built-in LOCATE_MOUSE 
anytime after the first keyboard or mouse-button event. The built-in 
returns the location occupied by the pointer cursor at the time of the most 
recent keyboard or mouse button event. 

If there is no mouse information available (because no mouse button has 
been pressed or if the mouse has been disabled using SET (MOUSE)), 
LOCATE_MOUSE signals the status TPU$_MOUSEINV. 
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SIGNALED 


ERRORS 

TPU$_MOUSEINV 

WARNING 

The mouse position is not currently 
valid. 


TPU$_TOOFEW 

ERROR 

LOCATE_MOUSE requires three 
parameters. 


TPU$_TOOMANY 

ERROR 

LOCATE_MOUSE accepts at most 
three parameters. 


tpu$_baddelete 

ERROR 

You have specified a constant as 
one or more of the parameters. 


EXAMPLES 

D LOCATE_MOUSE (abc_window, x_l, Yl); 

The example returns the window and coordinate position of the pointer. 

§ PROCEDURE user_move_to_mouse 

LOCAL my_window, 
x_l, 

yl; 

my_window := 0; 
x_l := 0; 
yl := 0; 

IF (LOCATE__MOUSE (my_window, Yl) <> 0) 

THEN 

IF (CURRENT_WINDOW <> my_window) 

THEN 

POSITION (my__window) ; 

UPDATE (my__window) ; 

ENDIF; 

CURSOR_VERTICAL (yl - (CURRENT_ROW - GET_INFO 

(my_window, ''visible_top") + 1) ) ; 

CURSOR_HORIZONTAL (CURRENT_COLUMN - x_l); 

ENDIF; 

ENDPROCEDURE; 

Binding the userjnoveJtojnouse procedure to a mouse button moves 
the cursor to the mouse location. The userjnove_tojnouse procedure is 
essentially equivalent to POSITION (MOUSE). 

Note that CURRENT.ROW and CURRENT_COLUMN return screen- 
relative location information, while LOCATE_MOUSE returns window- 
relative location information. 

@ status := LOCATE_MOUSE (new__window, x_value, y_value); 

The previous statement returns an integer in the variable status indicating 
whether the pointer cursor was found in a window, the window in the 
parameter newjuuindow where the mouse was found, an integer in the 
parameter x_value specifying the pointer cursor's location in the horizontal 
dimension, and an integer in the parameter yjjalue specifying the pointer 
cursor’s location in the vertical dimension. 
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LOOKUP KEY 


Returns the executable code or the comment that is associated with the key 
you specify. The code can be returned as a program or as a learn sequence. 
The comment is returned as a string. 


FORMAT 


' integer 

learn_sequence 1 
program j 

. Strings 

f COMMENT 
(key-name, KEY_MAP 
I PROGRAM 


LOOKUP_KEY 


( , string 1 
\ , string2 



PARAMETERS 


key-name 

A VAXTPU key name for a key or a combination of keys. See Table 2-1 for 
a list of the VAXTPU key names for the VTSOO-series, VT200-series, and 
VTlOO-series keyboards. 


COMMENT 

A keyword specifying that the LOOKUP_KEY built-in is to return the 
comment supplied when the key was defined. If no comment was supplied, 
the LOOKUP_KEY built-in returns the integer zero. 

KEY_MAP 

A keyword specifying that the LOOKUP_KEY built-in is to return the key 
map in which the key’s definition is stored. If you specify a key that is not 
defined in any key map, LOOKUP_KEY returns a null string. 

PROGRAM 

A ke 3 rword specifying that the LOOKUP_KEY built-in is to return the 
program or learn sequence boimd to the key specified. If the key is not 
defined, the LOOKUP_KEY built-in returns the integer 0. 

stringl 

The name of the key map from which the LOOKUP_KEY built-in is to 
obtain the key definition. Use this optional parameter if the key is defined 
in more than one key map. If you do not specify a key map or a key map 
list for the third parameter, the first definition found for the specified key 
in the key map hst bound to the current buffer is returned. 

string2 

The name of the key map list from which the LOOKUP_KEY built-in is to 
obtain the key definition. Use this optional parameter if the key is defined 
in more than one key map list. If you do not specify a key map or a key 
map list for the third parameter, the first definition found for the specified 
key in the key map list bound to the current buffer is returned. 
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DESCRIPTION 


SIGNALED 

ERRORS 


VAXTPU Built-In Procedures 

LOOKUP_KEY 


• integer — The integer 0. This value is returned if the key specified as 
a parameter has no definition. 

• leam_sequence — The learn sequence bound to the key specified as 
a parameter. 

• program — The program bound to the key specified as a parameter. 

• strings — If you specified COMMENT as the second parameter, 
Strings is the comment bound to the key specified as the first 
parameter. If you specified KEY_MAP as the second parameter, 
strings is the string naming the key map in which the key definition 
was found. 


The LOOKUP_KEY built-in procedure can return a program, a learn 
sequence, a string, or the integer 0 (0 means that the key has no 
definition). 

LOOKUP_KEY is useful when you are defining keys temporarily dining 
an editing session and you want to check the existing definitions of a key. 


TPU$_NOTDEFINABLE 

WARNING 

Argument is not a valid reference 
to a key. 

TPU$_NOKEYMAP 

WARNING 

Argument is not a defined key 
map. 

TPU$_NOKEYMAPLIST 

WARNING 

Argument is not a defined key map 
list. 

TPU$_KEYMAPNTFND 

WARNING 

The specified key map is not 
found. 

TPU$_EMPTYKMLIST 

WARNING 

The specified key map list contains 
no key maps. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
LOOKUP_KEY built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the LOOKUP_KEY built-in. 

TPU$_NEEDTOASSIGN 

ERROR 

LOOKUP_KEY must be on the 
right-hand side of an assignment 
statement. 

TPU$JNVPARAM 

ERROR 

Wrong type of data sent to the 
LOOKUP^KEY built-in. 

TPU$_BADKEY 

ERROR 

An unknown keyword has been 
used as an argument. Only 
PROGRAM, COMMENT, and 
KEY_MAP are valid keywords. 
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EXAMPLES 

Q programx ;= LOOKUP_KEY (keyl, PROGRAM) 

This assignment statement returns the executable code that is associated 
with keyl. The second keyword, PROGRAM, indicates that the result is 
returned to a variable of type program or learn. 

§ PROCEDURE user_what_is_coinment 

MESSAGE (LOOKUP_KEY (LAST_KEY, COMMENT)); 

ENDPROCEDURE; 

This procedure displays in the message area the comment that you 
included with your key definition for the last key that you typed. 

§ PROCEDURE user_get_key__info 
LOCAL key__to_interpret, 
key__info; 

MESSAGE ("Press the key you want information on: "); 
key_to_interpret := READ_KEY; 

key_info := LOOKUP_KEY (key_to_interpret, COMMENT); 

IF key_info <> 

THEN 

MESSAGE ("Comment: " + key___info) ; 

ELSE 

MESSAGE ("No comment is associated with that key.”); 

ENDIF; 

ENDPROCEDURE; 

This procedure returns the comment associated with a particular key. 

Q key_map_name := LOOKUP_KEY (RET_KEY, KEY_MAP, "tpu$key_map_list") ; 

IF LENGTH (key_map_name) = 0 
THEN 

MESSAGE ("RET_KEY is undefined"); 

ELSE 

MESSAGE ("RET_KEY is defined in key map " + key_map__name); 

ENDIF; 

This procedure returns the key map within the key map list TPU$KEY_ 
MAP.LIST in which the RETURN key is defined. 

g PROCEDURE shift_key_handler (key_map_list_name); 

LOCAL bound__program; 

bound_program := LOOKUP__KEY (READ_KEY, PROGRAM, "key_map__list__name”) ; 

IF bound__program <> 0 
THEN 

EXECUTE (bound__program) ; 

ELSE 

MESSAGE ("Attempt to execute undefined key"); 

ENDIF; 

ENDPROCEDURE; 
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red_keys := CREATE_KEY_MAP ("red_keys"); 

red_key_map_list := CREATE_KEY_MAP_LIST ("red_key_map_list", 
red_keys); 

DEFINE_KEY ("shift_key_handler (red_key_map_list)", PF3, 

"RED shift key"); 

This procedure implements multiple shift keys. 
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MANAGE WIDGET 



Makes the specified widget instances visible, provided that the specified 
widgets’ parent is also visible. 

FORMAT 

MANAGE_WIDGET (widget [, widget... ]) 

PARAMETERS 

widget 

The widget instance to be managed. 

DESCRIPTION 

This built-in performs the same functions as the X Toolkit MANAGE 
CHILD and MANAGE CHILDREN routines. 

If you have multiple children of a single widget that you want to manage, 
include them in a single call to MANAGE_WIDGET. Managing several 
widgets at once is more efficient than managing one widget at a time. 

All widgets passed in the same MANAGE_WIDGET operation must have 
the same parent. 

SIGNALED 

ERRORS 

TPU$JNVPARAM ERROR You specified a parameter of the 

wrong type. 

TPU$ TOOFEW ERROR Too few arguments passed to the 

MANAGE_WIDGET bulit-in. 

TPU$_NORETURNVALUE ERROR MANAGE_WIDGET cannot return 

a vaiue. 

TPU$_REQUIRESDECW ERROR You can use the MANAGE_ 

WIDGET built-in only if you are 
using DECwindows VAXTPU. 

TPU$_WIDMISMATCH ERROR You have specified a widget whose 

class is not supported. 

EXAMPLE 

For a sample procedure using the MANAGE_WIDGET built-in, see 
Example B-2. 
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MAP 

Associates a buffer with a window and causes the window or widget to 
become visible on the screen. Before using MAP, you must aiready have 
created the widget, buffer, and window that you specify as parameters. See 
CREATE_WIDGET, CREATE_BUFFER, and CREATE_WINDOW. 

FORMAT 

MAP }; 

PARAMETERS 

window 

The window you want to map to the screen. 

buffer 

The buffer you want to associate with the window. 

widget 

The widget instance you want to make visible. 

DESCRIPTION 

The window and buffer that you use as parameters become the current 
window and the current buffer, respectively. The map operation 
synchronizes the cursor position with the editing point in the buffer. 

If the window is not already mapped to the buffer when you use MAP, 
VAXTPU puts the cursor back in the last position the cursor occupied the 
last time the window was the current window. 

MAP may cause other windows that are mapped to the screen to be 
partially or completely occluded. If MAP causes the new window to 
segment another window into two pieces, only the upper part of the 
segmented window remains visible and continues to be updated. The 
lower part of the segmented window is erased on the next screen update. 

If you remove the window that is segmenting another window, YAXTPU 
repaints the screen so that the window that was segmented regains its 
original size and position on the screen. 

In DECwindows, MAP also maps the VAXTPU main widget if it has not 
already been mapped. 

Note that if you execute MAP within a procedure, the screen is not 
updated to reflect such operations as window repainting, line erasure, 
or new mapping until the procedure has finished executing and control 
has returned to the screen manager. If you want the screen to reflect 
the changes before the entire program is executed, you can force the 
immediate update of a window by including the following statement in the 
procedure before any statements containing the MAP built-in: 

UPDATE (WINDOW) ; 
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SIGNALED 

ERRORS 


TPU$_TOOFEW 

ERROR 

MAP requires at least two 
parameters. 

TPU$_TOOMANY 

ERROR 

You specified more than two 
parameters. 

TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 

TPU$_MAXMAPPEDBUF 

WARNING 

The buffer is already mapped to 
the maximum number of windows 
allowed by VAXTPU. 


EXAMPLES 

Q MAP (main_window, main__buffer) 

This statement associates the main buffer with the main window and 
maps the main window to the screen. You must have established the 
main buffer and the main window with CREATE_BUFFER and CREATE,. 
WINDOW before you can use them as parameters for MAP. 


PROCEDURE user_message_window 


inessage_buffer := CREATE_BUFFER ("message”)/ 
SET (EOB_TEXT, message__buffer, 

SET (NO__WRITE, message_buf fer) ; 

SET (SYSTEM, message_buffer); 

message__window := CREATE_WINDOW (23, 2, OFF) ; 
SET (VIDEO, message_window, NONE); 

MAP (message_window, message_buffer); 
ENDPROCEDURE; 


This procedure creates a message buffer and a message window. It then 
associates the message buffer with the message window and maps the 
message window to the screen. 

@ MAP (example_widget); 

T his statement causes the widget assigned to the variable example_widget 
to become visible if the widget has been created and managed but not 
mapped. For more information on how to map widgets without managing 
them, see the description of the SET (MAPPED_WHEN_MANAGED) 
built-in. 
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MARK 

Returns a marker for the editing point in the current buffer. You must specify 
how the marker is to be displayed on the screen (no special video, reverse 
video, bolded, blinking, or underlined). 

FORMAT 

f BLINK 

BOLD 

marker := MARK (< 0 

REVERSE 

1 UNDERLINE J 

PARAMETERS 

BUNK 

A keyword directing VAXTPU to display the marker in blinking rendition. 

BOLD 

A keyword directing VAXTPU to display the marker in bold rendition. 

FREE_CURSOR 

A keyword directing VAXTPU to create a free marker (that is, a marker 
not bound to a character). Specifying the parameter FREE_CURSOR does 
not create a free marker unless the editing point is before the beginning of 
a line, after the end of a line, in the middle of a tab, or below the bottom of 
a buffer when the statement MARK (FREE_CURSOR) is executed. If the 
editing point is on a character when the statement is executed, the marker 
is bound. A free marker has no video attribute. 

NONE 

A keyword directing VAXTPU to apply no video attributes to the marker. 

REVERSE 

A keyword directing VAXTPU to display the marker in reverse video. 

UNDERLINE 

A keyword directing VAXTPU to underline the marker. 

DESCRIPTION 

This built-in procediire can be used to establish place holders, or 
“bookmarks.” 

A marker can be either bound or free. For more information on how 
these markers differ, see Chapter 2. 

To create a bound marker, use the MARK built-in with any of its 
parameters except FREE_CURSOR. This operation creates a bound 
marker even if the editing point is beyond the end of a hne, before the 
beginning of a line, in the middle of a tab, or beyond the end of a buffer. To 
create a bound cursor in a location where there is no character, VAXTPU 
fills the space between the marker and the nearest character with padding 
space characters. 
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A bound marker is tied to the character at which it is created. If the 
character tied to the marker moves, the marker moves also. If the 
character tied to the marker is deleted, the marker moves to the nearest 
character position. The nearest character position is determined in the 
following way: 

1 If there is a character position on the same line and to the right, the 
marker moves to this position, even if the position is at the end of the 
line. 

2 If the line on which the marker is located is deleted, the marker moves 
to the first position on the following line. 

You can move one column past the last character in a line and place a 
marker there. However, the video attribute for the marker is not visible 
unless a subsequent operation puts a character under the marker. 

If you use a marker at the end of a line as part of a range, it is included in 
the range even though the marker is not positioned on a character. 

A marker is free if the following conditions are true: 

• You used the statement marker ^variable := MARK(FREE_CURSOR) to 
create the marker. 

• There was no character in the position marked by the editing point at 
the time you created the marker. 

VAXTPU keeps track of the location of a free marker by measuring the 
distance between the marker and the character nearest to the marker. 

If you move the character from which VAXTPU measures distance to 
a free marker, the marker moves too. VAXTPU preserves a uniform 
distance between the character and the marker. If you collapse white 
space containing one or more free markers (for example, if you delete a tab 
or use the APPEND_LINE built-in), VAXTPU preserves the markers and 
binds them to the nearest character. 

If the current buffer is mapped to a visible window, the MARK built-in 
causes the screen manager to s 3 nichronize the editing point, which is 
a buffer location, with the cursor position, which is a window location. 
Unless you specify the parameter FREE.CURSOR, using the MARK built- 
in may result in the insertion of padding spaces or lines into the buffer if 
the cursor position is before the beginning of a line, in the middle of a tab, 
beyond the end of a line, or after the last line in the buffer. 


SIGNALED 

ERRORS 

TPU$_TOOFEW 

ERROR 

MARK requires one parameter. 

TPU$_TOOMANY 

ERROR 

MARK accepts only one 
parameter. 


TPU$_NEEDTOASSIGN 

ERROR 

The MARK built-in must be on the 
right-hand side of an assignment 
statement. 
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TPU$_NOCURRENTBUF 

WARNING 

You must be positioned in a buffer 
to set a marker. 

TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 

TPU$_BADKEY 

ERROR 

The keyword must be NONE, 
BOLD, BLINK, REVERSE, 
UNDERLINE, or FREE_CURSOR. 

TPU$_UNKKEYWORD 

ERROR 

You have specified an unknown 
keyword. 

TPU$JNSVIRMEM 

FATAL 

There is not enough memory to 
create the marker. 


EXAMPLES 

0 user_mark := MARK (NONE) 

This assignment statement places a marker at the editing point. There 
are no video attributes applied to the marker. 

g user_mar)c_under := MARK (UNDERLINE) 

This assignment statement places a marker at the row and column 
position that corresponds to the editing point. The character tied to 
the marker is underlined. 

g my_mar)cl := MARK (UNDERLINE); 
my_marl<;2 := MARK (BLINK); 

These assignment statements place a marker at the row and column 
position that corresponds to the editing point. The character tied to the 
marker is underlined and blinks. 

Q PROCEDURE user_paste 

temp_pos := MARK (NONE); 

POSITION (END_OF (paste_buffer)); 

MOVE_HORIZONTAL (-2); 

paste_text := CREATE_RANGE (BEGINNING_OF (paste_buffer), 

MARK (NONE), NONE); 

POSITION (temp_pos); 

COPY_TEXT (paste_text); 

ENDPROCEDURE; 


This procedure marks a temporary position at the current character 
position, and then goes to the paste buffer and creates a range of the 
contents of the paste buffer. VAXTPU then goes to temp_pos and copies 
the text from the paste buffer at the temporary position. 
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MATCH 

MATCH returns a pattern that matches from the editing point up to and 
including the sequence of characters specified in the parameter. 

FORMAT 

f buffer ] 

pattern := MATCH (< range > j 
[ string J 

PARAMETERS 

buffer 

An expression that evaluates to a buffer. MATCH forms a string from 
the contents of the buffer and stops matching when it finds the resulting 
string. 


range 

An expression that evaluates to a range. MATCH forms a string from 
the contents of the range and stops matching when it finds the resulting 
string. 


string 

An expression that evaluates to a string. MATCH stops matching when it 
finds this string. 

return value 

A variable of type pattern that matches text from the editing point up to 
and including the characters specified in the parameter. 

DESCRIPTION 

MATCH returns a pattern that matches any string ending in the 
specified sequence of characters. The matched string does not contain 
line terminators. 


SIGNALED 

ERRORS 

TPU$_NEEDTOASSIGN 

ERROR 

MATCH must appear in the right- 
hand side of an assignment 
statement. 


TPU$_TOOFEW 

ERROR 

MATCH requires at least one 
argument. 


TPU$_TOOMANY 

ERROR 

MATCH requires no more than 
one argument. 


TPU$_ARGMISMATCH 

ERROR 

Argument to MATCH has the 
wrong type. 


TPU$_CONTROLC 

ERROR 

You pressed CTRL/C during the 
execution of MATCH. 
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EXAMPLES 

D patl := MATCH ("abc") 

This assignment statement stores in patl a pattern that matches a string 
of characters starting with the editing point up to and including the 
characters "abc". 

§ PROCEDURE user_double_parens 

paren_text ;= "((' + MATCH ('))"); 

found_range := SEARCH_QUIETLY (paren_text, FORWARD, NO_EXACT); 

IF found_range =0 ! No match 

THEN 

MESSAGE ("No match found."); 

ELSE 

POSITION (found_range); 

ENDIF; 

ENDPROCEDURE; 

This procedure finds text within double parentheses. It moves the editing 
point to the beginning of the parenthesized text, if it is found. 
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MESSAGE 

Depending on the format you choose, either puts the characters that you 
specify into the message buffer, or eise fetches text associated with a 
message code, formats the text using FAO directives, and puts it in the 
message buffer. 

if you use the first format, MESSAGE inserts the characters in the string, 
range, or buffer that you specify into the message buffer, if one exists. 

(By defauit, VAXTPU looks for a buffer variabie that is named MESSAGE_ 
BUFFER.) If there is no message buffer, VAXTPU dispiays the message at 
the current location on the device pointed to by SYS$OUTPUT (usuaily your 
terminai). 

If you use the second format, MESSAGE fetches the text associated with 
a message code, formats the text using FAO directives, and dispiays the 
formatted message in the message buffer. (If there is no message buffer, 
VAXTPU dispiays the message on SYSIOUTPUT.) 


FORMATS 


MESSAGE r I I H, integen ]) 


MESSAGE ( 


( integer2 ' 
keyword 
string 
( buffer 

[, FAO-parameter [, FAO-parameters... ] ] J) 


[, integers 


PARAMETERS buffer 

The buffer containing the text that you want to include in the message 
buffer. 

range 

The range containing the text that you want to include in the message 
buffer. 

integerl 

An integer indicating the severity of the message placed in the message 
buffer. If you do not specify this parameter, no severity code is associated 
with the message. The allowable integer values and their meanings are as 
follows: 


Integer Meaning 

0 Warning 

1 Success 


7-266 













VAXTPU Built-In Procedures 

MESSAGE 


DESCRIPTION 


Integer Meaning 

2 Error 

3 Informational 

mteger2 

The integer representing the message code associated with the text to be 
fetched. 

keyword 

The VAXTPU keyword representing the message code associated with the 
text to be fetched. VAXTPU provides ke 3 rwords for all of the message codes 
used by VAXTPU and EVE. 

String 

Either a quoted string or a variable representing the text you want to 
include in the message buffer. 

integers 

A bit-encoded integer that specifies what fields of the message text 
associated with the message code from the first parameter are to be 
fetched. If the message flags are not specified or the value is zero, then 
the message flags set by the SET (MESSAGE_FLAGS) built-in procedure 
are used. 

Table 7-6 shows the message flags: 


Table 7-6 Message Flag Values 


Bit 

Constant 

Meaning 

0 

TPU$K_MESSAGE_TEXT 

Include text of message. 

1 

TPU$K_MESSAGE_ID 

Include message identifier. 

2 

TPU$K_MESSAGE_SEVERITY 

Include severity level indicator. 

3 

TPU$K_MESSAGE_FACILITY 

Include facility name. 


FAO-parameter 

One or more expressions that evaluate to an integer or string. The 
MESSAGE_TEXT built-in procedure uses these integers and strings as 
arguments to the $FAO system service, substituting the values into the 
text associated with the message code to form the resultant string. 

The FAO directives are listed in the description of $FAO in the VMS 
System Services Reference Manual. 


If you use the first format shown above, the MESSAGE built-in provides 
the user who is writing an editing interface with a method of displaying 
messages in a way that is consistent with the VAXTPU language. 

If you have associated a message buffer with a message window, and if the 
message window is mapped to the screen, the range you specify appears 
immediately in the message window on the screen. 
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If you have not associated a message buffer with a message window, 
messages are written to the buffer, but do not appear on the screen. 

If you use the second format shown above, the MESSAGE built-in places a 
formatted string in the message buffer. The difference between MESSAGE 
and MESSAGE_TEXT is that MESSAGE_TEXT simply returns the 
resulting string while MESSAGE places the resulting string in the 
message buffer. The string is specified by the message code passed as 
the first parameter and constructed according to the rules of the $FAO 
system service. The control string associated with the message code 
directs the formatting process, and the optional arguments are V2dues to 
be substituted into the control string. 

MESSAGE capitalizes the first character of the string placed in the 
message buffer. The MESSAGE_TEXT built-in, on the other hand, does 
not capitalize the first character of the returned string. 

Some FAO directives you can include as part of the message text are the 
following: 

!AS Inserts a string as is 

!OL Converts an integer to octal notation 

iXL Converts an integer to hexadecimal notation 

IZL Converts an integer to decimal notation 

iUL Converts an integer to decimal notation without adjusting for negative 

number 

ISL Converts an integer to decimal notation with negative numbers converted 

properly 

!/ Inserts a new line character (carriage return/line feed) 

l_ Inserts a tab 

1} Inserts a form feed 

!l Inserts an exclamation point 

l%S Inserts an s if the most recently converted number is not 1 

!%T Inserts the current time if you enter 0 as the parameter (you cannot pass 

a specific time because VAXTPU does not use quadwords) 

!%D Inserts the current date and time if you enter 0 as the parameter (you 

cannot pass a specific date because VAXTPU does not use quadwords) 


SIGNALED 

ERRORS 

TPU$_TOOFEW 

ERROR 

MESSAGE requires at least 
one argument. 


TPU$_TOOMANY 

ERROR 

MESSAGE cannot accept 
as many arguments as you 
have specified. 


TPU$_ARGMISMATCH 

ERROR 

You have specified an 
argument of the wrong type. 


TPU$JNVFAOPARAM 

WARNING 

Argument was not a string 
or integer. 
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TPU$JNVPARAM 

TPU$_FLAGTRUNC 

TPU$_SYSERROR 

TPU$JLLSEVERITY 

TPU$_MSGNOTFND 


ERROR 

INFORMATIONAL 

ERROR 

WARNING 

WARNING 


You have specified an 
argument of the wrong type. 

Message flag truncated to 4 
bits. 

Error fetching the message 
text. 

Illegal severity specified; 
VAXTPU used the severity 
"error." 

Message not found. 
VAXTPU returned default 
message. 


EXAMPLES 

D MESSAGE ("Hello") 


This statement writes the text "Hello" in the message area. 

§ PROCEDURE user_on__eol 

! test if at eol, return true or false 
MOVE_HORIZONTAL (1); 

IF CURRENT_OFFSET = 0 ! then we are on eol 

THEN 

user_on_end_of_line := 1; ! return true 

MESSAGE ("Cursor at end of line"); 

ELSE 

user_on__end_of_line := 0; .! return false 

MESSAGE ("Cursor is not at the end of line"); 

ENDIF; 

MOVE_HORIZONTAL (-1); ! move back 

ENDPROCEDURE; 

This procedure determines whether the cursor is at the end of the line. It 
sends a text message to the message area on the screen about the position 
of the cursor. 

S MESSAGE (TPU$_OPENIN, TPU$K_MESSAGE_TEXT, "bat.bar"); 

The code fragment above fetches the text associated with the message code 
TPU$_OPENIN eind substitutes the string "BAT.BAR" into the message. 
All of the text of the message is fetched. The following string is displayed 
in the message bufifer: 

Error opening BAT.BAR as input 
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MESSAGE TEXT 


The MESSAGE_TEXT built-in procedure lets you do the following: 

• Fetch the text associated with a message code 

• Use FAO directives to specify how strings and integers should be 
substituted into the text 

For complete information on the $FAO and $GETMSG system services, see 
the VMS System Services Reference Manual. 


FORMAT 


string := MESSAGE_TEXT (| 1 1, integer2 [, FAO-parameter 

I FAO-parameters... J ]]) 


PARAMETERS integerl ^ 

The integer for the message code associated with the text that is to be 
fetched. 

keyword 

The keyword for the message code associated with the text that is to be 
fetched. VAXTPU provides keywords for all of the message codes used by 
VAXTPU and the EVE editor. 

mteger2 

A bit-encoded integer that specifies what fields of the message text 
associated with the message code from the first parameter are to be 
fetched. If the message flags are not specified or the value is 0, then the 
message flags set by the SET (MESSAGE_FLAGS) built-in procedure are 
used. 

Table 7-7 shows the message flags: 


Table 7-7 Message Flag Values 


Bit 

Constant 

Meaning 

0 

TPU$K_MESSAGE_TEXT 

Include text of message. 

1 

TPU$K_MESSAGEJD 

Include message identifier. 

2 

TPU$K_MESSAGE_SEVERITY 

Include severity level indicator. 

3 

TPU$K_MESSAGE_FACILlTY 

Include facility name. 


FAO-parameter 

One or more expressions that evaluate to an integer or string. The 
MESSAGE_TEXT built-in procedure uses these integers and strings as 
arguments to the $FAO system service, and substitutes the resultant 
values into the text associated with the message code to form the returned 
string. 
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The text associated with a message code that is fetched and formatted by 
MESSAGE_TEXT. 


MESSAGE_TEXT returns a formatted string, specified by the message 
code passed as the first parameter, and constructed according to the 
rules of the $FAO system service. The control string associated with the 
message code directs the formatting process, and the optional arguments 
are values to be substituted into the control string. 

MESSAGE_TEXT does not capitalize the first character of the returned 
string. The MESSAGE built-in, on the other hand, does capitalize the first 
character. 

Some FAO directives you can include as part of the message text are the 
following: 

!AS Inserts a string as is 

!OL Converts an integer to octal notation 

!XL Converts an integer to hexadecimal notation 

!ZL Converts an integer to decimal notation 

lUL Converts an integer to decimal notation without adjusting for negative 

number 

!SL Converts an integer to decimal notation with negative numbers converted 

properly 

!/ Inserts a new line character (carriage return/line feed) 

L Inserts a tab 

!} Inserts a form feed 

!! Inserts an exclamation point 

!%S Inserts an s if the most recently converted number is not 1 

!%T Inserts the current time if you enter 0 as the parameter (you cannot pass 

a specific time because VAXTPU does not use quadwords) 

!%D Inserts the current date and time if you enter 0 as the parameter (you 

cannot pass a specific date because VAXTPU does not use quadwords) 


TPU$JNVFAOPARAM 

WARNING 

Argument was not a string or 
integer. 

TPU$ 

ERROR 

MESSAGE_TEXT must 

NEEDTOASSIGN 


appear on the right-hand side 
of an assignment statement. 

TPUSJNVPARAM 

ERROR 

You have specified an 
argument of the wrong type. 

TPU$_TOOFEW 

ERROR 

MESSAGE_TEXT requires at 
least one parameter. 

TPU$_TOOMANY 

ERROR 

MESSAGE_TEXT accepts up 
to 20 FAO directives. 
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TPU$_FLAGTRUNC INFORMATIONAL Message flag truncated to 4 

bits. 

TPU$_SYSERROR ERROR Error fetching the message 

text. 


EXAMPLE 

all_message_flags := TPU$K_MESSAGE_TEXT OR 

TPU$K_MESSAGE_ID OR 
TPU$K_MESSAGE_SEVERITY OR 
TPU$K_MESSAGE_FACILITY; 

openin_text ;= MESSAGE_TEXT (TPU$_OPENIN, all_message_flags, 

"bat.bar"); 

This code fragment fetches the text associated with the message code 
TPU$_OPENIN and substitutes the string "BAT.BAK" into the message. 
All of the text of the message is fetched. The following string is stored in 
the variable openin_text: 

%TPO-E-OPENIN, error opening BAT.BAR as input 
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MODIFY. 

.RANGE 



Dynamically modifies a range. 


FORMAT 

MODIFY.RANGE (range. { }, 

( marker2 1 
' \ keywordi / 


[, keyword2 ]) 



PARAMETERS range 

The range to be modified. 


markerl 

The starting mark for the range. 

marker2 

The ending mark for the range. 

keywordi 

A keyword indicating the point in the buffer where you want the range 
to begin or end. Table 7-8 shows the valid ke3words and their meanings. 
Use of the delimiting keywords is more efficient than the BEGINNING_OF 
and END_OF built-ins. 


Table 7-8 MODIFY_RANGE Keyword Parameters 


Keyword 

Meaning 

LINE_BEGIN 

The beginning of the current buffer’s current line. 

LINE_END 

The end of the current buffer’s current line. 

BUFFER 

BEGIN 

Line 1, offset 0 in the current buffer. This is the first position 
where a character could be inserted, regardless of whether there 
is a character there. This is the same as the point referred to by 
BEGINNING_OF (CURRENT_BUFFER). 

BUFFER_END 

The last position in the buffer where a character could be inserted, 
regardless of whether there Is a character there. This Is the same 
as the point referred to by END OF (CURRENT BUFFER). 

keyword2 


A keyword specifying the new video attribute for the range. By default, 
the attribute is not modified. You can use the keywords NONE, 
REVERSE, UNDERLINE, BLINK, or BOLD to specify this parameter. 
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QggQPIpyiQ^ You can use MODIFY_RANGE to specify a new starting mark and ending 

mark for an existing range. 

MODIFY_RANGE can also change the characteristics of the range without 
deleting, re-creating, and repainting all the characters in the range. Using 
MODIFY_RANGE, you can direct VAXTPU to apply or remove the range’s 
video attribute to or from characters as you select and unselect text. 

Ranges are limited to one video attribute at a time. Specifying a video 
attribute different from the present attribute causes VAXTPU to apply the 
new attribute to the entire visible portion of the range. 

If the video attribute stays the same and only the markers move, the only 
characters that are refreshed are those visible characters newly added to 
the range and those visible characters that are no longer part of the range. 


SIGNALED 

ERRORS 


TPU$_NOTSAMEBUF 

WARNING 

The first and second marker are in 
different buffers. 

TPU$_ARGMISMATCH 

ERROR 

The data type of the indicated 
parameter is not supported by the 
MODIFY_RANGE built-in. 

TPU$_BADKEY 

WARNING 

You specified an illegal keyword. 

TPU$JNVPARAM 

ERROR 

You specified a parameter of the 
wrong type. 

TPU$_MODRANGEMARKS 

ERROR 

MODIFY_RANGE requires either 
two marker parameters or none. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
MODIFY_RANGE built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the MODIFY_RANGE built-in. 

TPU$_NORETURNVALUE 

ERROR 

MODIFY_RANGE cannot return a 
vaiue. 


EXAMPLES 

D begin_mark ;= MARK (BOLD); 

POSITION (MOUSE); 
finish_mark := MARK (BOLD); 

this_range := CREATE_RANGE (begin_mark, finish__mark, BOLD); 

I 

! . (User may have moved mouse) 

I 

POSITION (MOUSE); 
new_mark := MARK (BOLD); 

IF new_mark <> finish__mark 
THEN 

MODIFY_RANGE (this_range, begin_mark, new_mark, BOLD); 
ENDIF; 
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moved the pointer cursor, the code fragment modifies the range to reflect 
the new pointer cursor location. 

g MODIFY_RANGE (this_range, , ,BLINK); 

This statement sets the video attribute of the range this_range to BLINK 

S PROCEDURE move_mark (place__to_start, direction); 

POSITION (place__to_start) ; 

IF direction = 1 
THEN 

MOVE_HORIZONTAL (1); 

ELSE 

MOVE__HORIZONTAL (-1) ; 

ENDIF; 

RETURN MARK (NONE); 

ENDPROCEDURE; 

PROCEDURE user__shrink_and_enlarge_range 

LOCAL start_mark, 
end__mark, 
direction, 
dynamic_range, 
rendition, 
remembered__range ; 

! The following lines 
! create a range that 
! shrinks and grows and 
! a range that defines 
! the limits of the dynamic 
! range. 

POSITION (LINE_BEGIN); 
start_mark := MARK (NONE); 

POSITION (LINE_END); 
end_mark := MARK (NONE); 
rendition := REVERSE; 

remembered__range ;= CREATE_RANGE (start__mark, end__mark, NONE); 
dynamic__range := CREATE_RANGE (start_mark, end__mark, rendition); 

! The following lines 
! shrink and enlarge 
! the dynamic range. 

direction := 1; 

LOOP 

UPDATE (CURRENT_WINDOW); 

start_mark := move_mark (BEGINNING_OF (dynamic_range), direction); 
end_mark ;= move_mark (END_OF (dynamic__range), 1 - direction); 

MODIFY_RANGE (dynamic___range, start_mark, end_mark) ; 


7-275 









VAXTPU Built-In Procedures 

MODIFY RANGE 


IF start_mark > end_mark. 

THEN 

EXITIF READ__KEY = CTRL__Z_KEY; 
direction := 0; 

IF rendition = REVERSE 
THEN 

rendition BOLD; 

ELSE 

rendition := REVERSE; 

ENDIF; 

MODIFY_RANGE (dynamic_range, , , rendition); 
ENDIF; 

IF (start__mark = BEGINNING_OF (remembered_range)) OR 
(end_mark = END_OF (remembered_range)) 

THEN 

direction := 1; 

ENDIF; 

ENDLOOP; 

ENDPROCEDURE; 


These procedures cause the range dynamicj-ange to shrink to one 
character, then grow until it becomes as large as the range remembered_ 
range, 

Q PROCEDURE line_up__characters (text__range, lined_chars__pat) 

LOCAL 

range_start, 
range_end, 
temp_range, 
max_cols; 

range_end := END__OF (text_range); ! These statements store 

! the ends of the range 
! containing the text operated on. 

range__start := BEGINNING_OF (text_range) ; 

! The following statements 
! locate the portions of 
! text that match the pattern 
! and determine which is 
! furthest to the right. 

max__cols := 0; 

LOOP 

temp__range := SEARCH_QUIETLY (lined_chars_pat, REVERSE, EXACT, text_range); 
EXITIF temp__range = 0; 

POSITION (temp_range); 

IF GET__INFO (MARK (NONE), "offset_column") > max__cols 
THEN 

max_cols := GET__INFO (MARK (NONE), "offset_column"); 

ENDIF; 

MOVE_HORIZONTAL (-1); 

MODIFY_RANGE (text___range, BEGINNING_OF (text_range) , MARK (NONE) ) ; 

ENDLOOP; 
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! The following lines 
! locate matches to the 

text_range := CREATE_RANGE (range_start, range_end); ! pattern and align them 

! with the rightmost 
! piece of matching text. 

LOOP 

temp_range := SEARCH__QUIETLY (lined_chars_pat, FORWARD, EXACT, text_range); 
EXITIF temp_range = 0; 

POSITION (temperange); 

IF GET_INFO (MARK (NONE), "offset_column") < max_cols 
THEN 

COPY^TEXT (" " * (max__cols - GET_INFO (MARK (NONE), "offset_column")) ) ; 
ENDIF; 

MOVE_HORIZONTAL (1); 

MODIFY_RANGE (text_range, END_OF (text_range), MARK (NONE)); 

ENDLOOP; 

I 

! Restore the range to its original state, plus a reverse attribute. 

j 

text_range := CREATE_RANGE (range_start, range__end, REVERSE); ! This line 

! restores the 
! range to its 
! original state 
! and displays 
! the contents 
! in reverse video. 

ENDPROCEDURE; 

This procedure aligns text that conforms to the pattern specified in the 
second parameter. For example, if you want to align all comments in a 
piece of VAXTPU code, you would pass as the second parameter a pattern 
defined as an exclamation point followed by an arbitrary amount of text or 
whitespace and terminated by a line end. 

The procedure is passed a range of text. As the procedure searches the 
range to identify the rightmost piece of text that matches the pattern, 
the procedure modifies the range to exclude any matching text. Next, the 
procedure searches the original range again and inserts padding spaces 
in front of each instance of matching text, making the text align with the 
rightmost instance of matching text. 
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MOVE HORIZONTAL 



Changes the editing point in the current buffer by the number of characters 
you specify. 

FORMAT 

MOVE_HORIZONTAL (integer) 

PARAMETERS 

Integer 

The signed integer value that indicates the number of characters the 
editing point should be moved. A positive integer specifies movement 
toward the end of the buffer. A negative integer specifies movement 
toward the beginning of the buffer. 

VAXTPU does not count the column where the editing point is located 
when determining where to establish the new editing point. VAXTPU does 
count the end-of-line (the column after the last text character on the line) 
when determining where to establish the new editing point. 

DESCRIPTION 

The horizontal adjustment of the editing point is tied to text. MOVE_ 
HORIZONTAL crosses line boundaries to adjust the current character 
position. 

You cannot see the adjustment caused by MOVE_HORIZONTAL unless 
the current buffer is mapped to a visible window. If it is, VAXTPU scrolls 
text in the window, if necessary, so that the editing point you establish 
with MOVE_HORIZONTAL is within the scrolling limits set for the 
window. 

If you try to move past the beginning or the end of a buffer, VAXTPU 
displays a warning message. 

Using MOVE_HORIZONTAL may cause VAXTPU to insert padding 
spaces or blank lines in the buffer. MOVE_HORIZONTAL causes the 
screen manager to place the editing point at the cursor position if the 
current buffer is mapped to a visible window. (For more information on 
the distinction between the cursor position and the editing point, see 
Chapter 6.) If the cursor is not located on a character (that is, if the cursor 
is before the beginning of a line, beyond the end of a line, in the middle of 
a tab, or below the end of the buffer), VAXTPU inserts padding spaces or 
blank lines into the buffer to fill the space between the cursor position and 
the nearest text. 

SIGNALED 

ERRORS 

TPU$_TOOFEW ERROR MOVE_HORIZONTAL requires 

one parameter. 

TPU$_TOOMANY ERROR You specified more than one 

parameter. 
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TPU$JNVPARAM 

ERROR 

The specified parameter has the 
wrong type. 

TPU$_NOCURRENTBUF 

WARNING 

You are not positioned in a buffer. 

TPU$_ENDOFBUF 

WARNING 

You are trying to move forward 
past the last character of the 
buffer. 

TPU$_BEGOFBUF 

WARNING 

You are trying to move in reverse 
past the first character of the 
buffer. 


EXAMPLES 

Q MOVE_HORIZONTAL (+5) 

This statement moves the editing point five characters toward the end of 
the current buffer. 

§ PROCEDURE user_move_by_lines 

IF CURRENT_DIRECTION = FORWARD 
THEN 

MOVE_VERTICAL (8) 

ELSE 

MOVE__VERTICAL(- 8) 

ENDIF; 

MOVE_HORIZONTAL (-CURRENT_OFFSET); 

ENDPROCEDURE; 


This procedure moves the editing point by sections that are eight lines 
long, and uses MOVE_HORIZONTAL to put the editing point at the 
beginning of the line. 
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MOVE TEXT 



Depending on the mode of the current buffer, moves the text you specify and 
inserts or ovenwrites it in the current buffer. When you move text with range 
and buffer parameters, you remove it from its originai iocation. For information 
on how to copy text instead of removing it, see the description of the COPY_ 
TEXT built-in. 

FORMAT 

r buffer ] 

Irange2 := IMOVE_TEXT ^ rangel W 

[ string j 

PARAMETERS 

buffer 

The buffer from which text is moved. 

rangel 

The range from which text is moved. 

string 

A string representing the text you want to move. Text is not removed from 
its original location with this argument. 

return value 

The range where the copied text has been placed. 

DESCRIPTION 

If the current buffer is in insert mode, the text you specify is inserted 
before the editing point in the current buffer. If the current buffer is in 
overstrike mode, the text you specify replaces text starting at the current 
position and continuing for the length of the string, range, or buffer. 

Markers and ranges are not moved with the text. If the text of a marker 
or a range is moved, the marker or range structure and any video attribute 
that you specified for the marker or range are moved to the next closest 
character, which is always the character following the marker or range. To 
remove the marker or range structure, use the built-in procedure DELETE 
or set the variable to which the range is assigned to 0. 

MOVE.TEXT is similar to COPY^TEXT. However, MOVE_TEXT erases 
the text from its original string, range, or buffer, while COPY_TEXT just 
makes a copy of the text and places the copy at the new location. 

You cannot add a buffer or a range to itself. If you try to do so, VAXTPU 
issues an error message. If you try to insert a range into itself, part of the 
range is copied before VAXTPU signals an error. If you try to overstrike a 
range into itself, VAXTPU may or may not signal an error. 
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Using MOVE_TEXT may cause VAXTPU to insert padding spaces or blank 
lines in the buffer. MOVE__TEXT causes the screen manager to place the 
editing point at the cursor position if the current buffer is mapped to a 
visible window. (For more information on the distinction between the 
cursor position and the editing point, see Chapter 6.) If the cursor is not 
located on a character (that is, if the cursor is before the beginning of a 
line, beyond the end of a line, in the middle of a tab, or below the end of 
the buffer), VAXTPU inserts padding spaces or blank lines into the buffer 
to fill the space between the cursor position and the nearest text. 


SIGNALED 

ERRORS 


TPU$_NOCACHE 

ERROR 

There is not enough memory to 
allocate a new cache. 

TPU$_TOOFEW 

ERROR 

MOVE_TEXT requires one 
argument. 

TPU$_TOOMANY 

ERROR 

MOVE__TEXT accepts only one 
argument. 

TPU$_ARGMISMATCH 

ERROR 

The argument to MOVE_TEXT 
must be a buffer, range, or string. 

TPU$_NOTMODIFIABLE 

ERROR 

You cannot copy text Into an 
unmodifiabie buffer. 

TPU$_MOVETOCOPY 

WARNING 

MOVE__TEXT was able to copy 
the text Into the current buffer but 
could not delete It from the source 
buffer because the source buffer is 
unmodifiabie. 


EXAMPLES 

Q MOVE_TEXT (main_buffer) 

If you are using insert mode for text entry, this statement causes the 
text from mainjbuffer to be placed in front of the current position in the 
current buffer. The text is removed from mainjbuffer. 

g PROCEDURE user_move_text 
LOCAL this_mode; 

! Save mode of current buffer in this_mode 

this_mode := GET_INFO (CURRENT_BUFFER, "mode"); 

! Set current buffer to insert mode 
SET (INSERT, CURRENT_BUFFER); 

! Move the scratch buffer text to the current buffer 
MOVE_TEXT (scratch_buffer); 

! Reset current buffer to original mode 
SET (this_mode, CURRENT_BUFFER); 

ENDPROCEDURE; 


This procedure puts the text from the scratch buffer before the editing 
point in the main buffer. The text in the scratch buffer is removed; no 
copy of it is left there. 
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MOVE VERTICAL 



Modifies the editing point in the current buffer by the number of lines you 
specify. 

FORMAT 

MOVE_VERTICAL (integer) 

PARAMETERS 

integer 

The signed integer value that indicates the number of lines that the 
editing point should be moved. A positive integer specifies movement 
toward the end of the buffer. A negative integer specifies movement 
toward the beginning of the buffer. 

DESCRIPTION 

The ac^ustment that MOVE_VERTICAL makes is tied to text. VAXTPU 
tries to retain the same character offset relative to the beginning of the 
line when moving vertically. However, if there are tabs in the lines, or the 
lines have different margins, the editing point does not necessarily retain 
the same column position on the screen. 

By default, VAXTPU keeps the cursor at the same offset on each line. 
However, since VAXTPU counts a tab as one character regardless of how 
wide the tab is, the cursor’s column position may vary greatly even though 
the offset is the same. 

To keep the cursor in approximately the same column on each line, use the 
following statement: 

SET (COLUMN_MOVE_VERTICAL, ON) 

This statement directs VAXTPU to keep the cursor in the same column 
unless a tab character makes this impossible. If a tab occupies the column 
position, VAXTPU moves the cursor to the beginning of the tab. 

You cannot see the adjustment caused by MOVE_VERTICAL unless the 
current buffer is mapped to a visible window. If it is, VAXTPU scrolls text 
in the window, if necessary, so that the editing point you establish with 
MOVE_VERTICAL is within the scrolling limits set for the window. 

Using MOVE_VERTICAL may cause VAXTPU to insert padding spaces or 
blank lines in the buffer. MOVE_VERTICAL causes the screen manager 
to place the editing point at the cursor position if the current buffer is 
mapped to a visible window. (For more information on the distinction 
between the cursor position emd the editing point, see Chapter 6.) If the 
cursor is not located on a character (that is, if the cursor is before the 
beginning of a line, beyond the end of a hne, in the middle of a tab, or 
below the end of the buffer), VAXTPU inserts padding spaces or blank 
lines into the buffer to fill the space between the cursor position and the 
nearest text. 

If you try to move past the begiiming or end of a buffer, VAXTPU displays 
a warning message. 
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SIGNALED 

ERRORS 


TPU$_TOOFEW 

ERROR 

MOVE_VERTICAL requires at 
least one parameter. 

TPU$_TOOMANY 

ERROR 

You specified more than one 
parameter. 

TPUSJNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 

TPU$_BEGOFBUF 

WARNING 

You are trying to move backward 
past the first character of the 
buffer. 

TPU$_ENDOFBUF 

WARNING 

You are trying to move forward 
past the last character of the 
buffer. 

TPU$_NOCURRENTBUF 

WARNING 

You are not positioned in a buffer. 


EXAMPLES 

D MOVE_VERTICAL (+5) 

This statement moves the editing point in the current buffer down five 
lines toward the end of the buffer. 

§ PROCEDURE user_move_8_lines 

IF CURRENT_DIRECTION = FORWARD 
THEN 

MOVE_VERTICAL (8); 

ELSE 

MOVE_VERTICAL (- 8); 

ENDIF; 

MOVE_HORIZONTAL(~ CURRENT_OFFSET); 

ENDPROCEDURE; 


This procedure moves the editing point by sections that are eight lines 
long. 
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NOTANY 

Returns a pattern that matches a specific number of characters not in the 
string, buffer, or range that is used as a parameter. 

FORMAT 

r buffer ) 

pattern := NOTANY (< range > f, integerf ]) 

[ string ) 

PARAMETERS 

buffer 

An expression that evaluates to a buffer. NOTANY matches any character 
not in the resulting buffer. 


range 

An expression that evaluates to a range. NOTANY matches any character 
not in the resulting range. 


String 

An expression that evaluates to a string. NOTANY matches any character 
not in the resulting string. 


integerl 

This integer value indicates how many contiguous characters NOTANY 
matches. The default value for this integer is 1. 

return value 

A pattern that matches characters not in the string, bufiFer, or range used 
as a parameter. 

DESCRIPTION 

NOTANY returns a pattern that matches one or more contiguous 
characters. NOTANY only matches characters that do not appear in the 
string, range, or buffer used as the first parameter. The second parameter 
determines the number of characters NOTANY must match. NOTANY 
does not match across line breaks. 


SIGNALED 

ERRORS 

TPU$_NEEDTOASSIGN 

ERROR 

NOTANY must appear in the 
right-hand side of an assignment 
statement. 


TPU$_TOOFEW 

ERROR 

NOTANY requires at least one 
argument. 


TPU$_TOOMANY 

ERROR 

NOTANY accepts no more than 
two arguments. 


TPU$_ARGMISMATCH 

ERROR 

NOTANY was given an argument 
of the wrong type. 
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TPU$JNVPARAM 


ERROR NOTANY was given an argument 
of the wrong type. 

WARNING NOTANY was given an argument 
less than the minimum value. 

ERROR You pressed CTRL/C during the 
execution of NOTANY. 


TPU$_MiNVALUE 


TPU$_CONTROLC 


EXAMPLES 


D patl := NOTANY ("XYZ") 


This assignment statement creates a pattern that matches the first 
character that is not an X, a Y, or a Z. The match fails if no character 
other than X, Y, or Z is found. 


patl := notany ("ABC", 2) 


This assignment statement creates a pattern that matches two characters, 
neither of which can be an A, a B, or a C. 


g a_buf := CREATE_BUFFER ("new buffer"); 
POSITION (a_buf); 

COPY_TEXT ("xy"); 

SPLIT_LINE; 

COPy_TEXT ("abc"); 
patl := NOTANY (a_buf); 


These VAXTPU statements create a pattern that matches any single 
character other than one of the characters a, b, c, x, and y. 


E! 


! The following procedure returns a marker pointing to 
! the next nonalphabetic character or the integer zero 
! if there are no more nonalphabetic characters. You 
! call the procedure in the following way: 

I 

! non_alpha_marker := user_search_for_nonalpha; 

PROCEDURE user_search_for_nonalpha 

LOCAL pat, 

f irst_non__alpha; 

pat ;== NOTANY ("abcdefghi jklmnopqrstuvwxyz"); 

first_non_alpha := SEARCH_QUIETLY (pat, FORWARD, NONEXACT); 

IF first_non_alpha <> 0 
THEN 

first_non_alpha := BEGINNING_OF (first_non_alpha); 
ENDIF; 

RETURN first_non__alpha; 

ENDPROCEDURE; 


This procedure starts at the current location and looks for the first 
nonalphabetic, nonlowercase character. The variable non_alpha_range 
stores the character that matches these conditions. 
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PAGE BREAK 



Specifies the form-feed character, ASCIi(12), as a portion of a pattern to be 
matched. 

FORMAT 

PAGE_BREAK 

PARAMETERS 

None. 

DESCRIPTION 

PAGE_BREAK matches the next form-feed character. This character has 
an ASCII value of 12. 

Although PAGE_BREAK behaves much like a built-in, it is actually a 
keyword. 

If the form-feed character is the only character on a line, PAGE_BREAK 
matches the whole hne. If the form-feed character is not the only character 
on a line, PAGE_BREAK matches only the form-feed character. 

SIGNALED 

ERROR 

PAGE_BREAK is a keyword and has no completion codes. 


EXAMPLE 

PROCEDURE user_next_page 
LOCAL next_page; 

next_page := SEARCH_QUIETLY (PAGE_BREAK, FORWARD); 

IF next_page <> 0 
THEN 

POSITION (next__page) ; 

ELSE 

POSITION (end_of (current_buffer)); 

ENDIF; 

ENDPROCEDURE; 

This procedure places the cursor on the next page in the current buffer. If 
you are already on the last page of a document, it places the cursor at the 
end of that document. 
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POSITION 


Ties the editing point to a specific character in a specific buffer, and moves 
the editing point to a specified record in the current buffer. The character 
and buffer in which POSITION establishes the editing point depend on which 
parameter you pass to POSITION. 


FORMAT 


POSITION 


' buffer 

BUFFER_BEGIN 
BUFFER_END 
integer 
LINE_BEGIN 
< LINE_END 
marker 
MOUSE 
range 
TEXT 
. window 


PARAMETERS buffer 

The buffer in which you want to establish the editing point. 

VAXTPU maintains an editing point in each buffer even when the buffer 
is not the current buffer. When you position to a buffer, the editing point 
that VAXTPU maintains becomes the active editing point. The location at 
which POSITION establishes the editing point is the last character that 
the cursor was on when the buffer was most recently current. 

BUFFER_BEGIN 

A ke)word directing VAXTPU to establish the editing point at the 
begiiming of the current buffer. Note that this is more efficient than 
using POSITION (BEGINNING.OF (CURRENT_BUFFER)). 

BUFFER_END 

A keyword directing VAXTPU to establish the editing point at the 
end of the current buffer. Note that this is more efficient than using 
POSITION (END_OF (CURRENT_BUFFER)). 

integer 

The number of the record where you want VAXTPU to position the editing 
point. 

A record number indicates the location of a record in a buffer. Record 
numbers are dsmamic; as you add or delete records, VAXTPU changes 
the number associated with a particular record, as appropriate. VAXTPU 
coimts each record in a buffer, regardless of whether the line is visible in a 
window, or whether the record contains text. 
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To position the editing point to a given record, specify the record number. 
The number can be in the range from 1 to the number of records in the 
buffer plus 1. For example, the following statement positions the editing 
point to record number 8 in the current buffer: 

POSITION (8); 

VAXTPU places the editing point on the first character of the record. 

Specifying a value of 0 has no effect. Specifying a negative number or a 
number greater thsin the number of records in the buffer plus 1 causes 
VAXTPU to signal an error. 

UNE_BEGIN 

A keyword directing VAXTPU to establish the editing point at the 
beginning of the current line. 

UNE_END 

A kejrword directing VAXTPU to establish the editing point at the end of 
the current line. 

marker 

The marker to which you want to tie the editing point. You can position 
either to a bound marker or a free marker. (For more information on the 
distinction between bound and free markers, see Chapter 2.) Positioning 
to a free marker does not cause VAXTPU to insert padding blanks between 
the nearest text and the free marker; such positioning establishes the 
editing point as free. (For more information on the distinction between 
free and detached editing points, see Chapter 6.) 

MOUSE 

A keyword directing VAXTPU to associate the editing point with the 
location of the pointer cursor. 

In DECwindows VAXTPU, you can use the statement POSITION 
(MOUSE) at any point after the first keyboard or mouse button event. 

The statement positions the editing point to the location occupied by the 
pointer cursor at the time of the most recent keyboard or mouse-button 
event. 

If the pointer cursor is on a window’s status line when POSITION 
(MOUSE) is executed, VAXTPU positions the editing point at the line 
just above the status line. 

If the pointer cursor is not located in a VAXTPU window at the time of 
the most recent keyboard or mouse-button event, POSITION (MOUSE) 
returns the status TPU$_NOWINDOW. 

In non-DECwindows VAXTPU, POSITION (MOUSE) is only vahd during 
a procedure that is executed as the result of a mouse click. At all other 
times, the mouse position is not updated. 

The statement POSITION (MOUSE) makes the window in which the 
pointer cursor is located the current window, and the buffer in which the 
pointer cursor is located the current buffer. 

range 

The range in which you want to place the editing point. The editing point 
is established at the beginning of the range. To establish the editing point 
at the end of the range, use the statement POSITION (END_OF (range)). 
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TEXT 

A keyword indicating that if the editing point is at a free-cursor location 
(a portion of the screen where there is no text), the POSITION built-in 
is to establish the editing point at the nearest location that has a text 
character in it. The character may be a space or an end of line. If you use 
POSITION (TEXT) when the editing point is already bound to a character, 
the built-in has no effect. 

window 

The window in which you want to establish the editing point. The window 
must be mapped to the screen. 

The location at which POSITION establishes the editing point is the last 
character that the cursor was on when the window was most recently 
current. If that character has been deleted, the editing point is the 
character closest to the last character that the cursor was on when the 
window was current. 

Positioning to a window causes the buffer associated with the window 
to become the current buffer. This is true whether you directly position 
to a window, or a new window is mapped as the result of a POSITION 
(MOUSE) statement. 

DESCRIPTION 

The editing point is the location in the current buffer where most editing 
operations are carried out. VAXTPU maintains a marker pointing to an 
editing point in each buffer, but only the editing point in the ciurent buffer 
is active. An editing point, whose location is always tied to a character 
in a buffer, is not necessarily the same as the cursor position, whose 
location is always tied to a position in a window. For more information 
on the distinction between the editing point and the cursor position, see 
Chapter 6. 

The POSITION built-in synchronizes the editing point and the cursor 
position if the current buffer is mapped to a visible window. POSITION 
also moves the editing point to the the specified record in the current 
buffer. 

When you pass the kesrword MOUSE to POSITION, the built-in 
establishes the mouse pointer’s location as the cursor position. POSITION 
also establishes the window in which the mouse pointer is located as the 
current window, eind establishes the buffer mapped to that window as the 
current buffer. 

Positioning to a buffer, a marjter, or a range does not necessarily move 
the cursor. VAXTPU does not change the cursor position iinless the cursor 
is in a window that is mapped to the buffer specified or implied by the 
POSITION parameter. For example, if you use POSITION to estabUsh 
the editing point in a buffer that is not mapped to a window, the cursor is 
unaffected by the POSITION operation. If you want to do visible editing, 
you should position to a window rather than a buffer. 

If you try to position to an invisible window, VAXTPU issues a warning 
message. 

For more information on the relationship between the editing point and 
the cursor position, see Chapter 6. 
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SIGNALED 

TPU$_TOOFEW 

ERROR 

POSITION requires one 

ERRORS 



parameter. 


TPU$_TOOMANY 

ERROR 

You specified more than one 


TPU$JNVPARAM 

ERROR 

parameter. 

One or more of the specified 


TPU$_ARGMISMATCH 

ERROR 

parameters have the wrong type. 
Wrong type of data sent to the 


TPU$_BADKEY 

WARNING 

built-in. 

You have specified an invalid 


TPU$_UNKKEYWORD 

ERROR 

keyword. 

You specified an unknown 


TPU$_BADVALUE 

ERROR 

keyword. 

You specified a record number 


TPU$_MOUSEINV 

WARNING 

less than 0 or greater than the 
length of the buffer plus 1. 

The mouse position is not currently 


TPU$_NOWINDOW 

WARNING 

valid. 

The pointer cursor was not located 


TPU$_WINDNOTMAPPED 

WARNING 

in a VAXTPU window at the time 
of the most recent keyboard or 
mouse-button event. 

Window is not mapped to the 


TPU$_WINDNOTVIS 

WARNING 

screen. 

Window is totally occluded. 


EXAMPLES 

Q POSITION (message_window) 

This statement establishes the editing point in the message window. Your 
position in the window is the same character position you occupied when 
you were last positioned in the window. 

g user_mark := MARK(NONE); 

POSITION (user_mark) 

These statements establish the editing point at the marker associated with 
the variable userjnark. 


PROCEDURE user_change__windows 

IF CURRENT_WINDOW = main_window 
THEN 

POSITION (extra__window) ; 

ELSE 

POSITION (main__window) ; 

ENDIF; 

ENDPROCEDURE; 

This procedure toggles the active editing point between two windows. 
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QUIT 

Leaves the editor without writing to a file. 

FORMAT 

QUIT }[, severity])] 

PARAMETERS 

ON 

A keyword indicating that VAXTPU should prompt to find out if the user 
really wants to quit with modified buffers. This is the default value. 

OFF 

A ke 3 nvord indicating that VAXTPU should quit without asking the user 
whether to quit with modified buffers. 

severity 

If present, the least significant two bits of this integer are used as the 
severity of the status VAXTPU returns to whatever invoked it. 


Value Severity 


0 Warning 

1 Success 

2 Error 

3 Informational 


It is not possible to force VAXTPU to return a fatal severity status. 


DESCRIPTION If you modify any buffers that are not set to NO^WRITE and you do 

not specify OFF as the first parameter to the QUIT built-in procedure, 
VAXTPU tells you that you have modified buffers and asks whether you 
want to quit. Enter Y (Yes) if you want to quit without writing out any 
modified buffers. Enter N (No) if you want to retain the modifications 
you have made and return to the editor. If you specify OFF as the first 
parameter to QUIT, VAXTPU quits without informing you that you have 
modified buffers. All modifications are lost because VAXTPU does not 
write out buffers when quitting. 

Journal files (if any) are deleted upon quitting. 

Use the EXIT built-in procedure when you have made changes and want 
to save them when you leave the editor. (For more information, see the 
description of EXIT.) 

Normally, when VAXTPU quits it returns a status of TPU$_QUITTING to 
whatever invoked it. This is a success status. 
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This feature is useful if you are using VAXTPU to create an application 
in which quitting, especially before the end of a series of statements 
executing in batch mode, is an error. 

A special use of the built-in procedure QUIT is at the end of your section 
file when you are compiling it for the first time. See Chapter 4 for 
information on creating section files. 


SIGNALED 

ERRORS 


TPU$_CANCELQUIT 

WARNING 

"NO" response was received 
from"... continue quitting?" 



prompt. 

TPU$_TOOMANY 

ERROR 

QUIT accepts no more than two 
arguments. 

TPU$JNVPARAM 

ERROR 

One of the arguments to QUIT has 
the wrong data type. 

TPU$_BADKEY 

WARNING 

QUIT accepts only the keywords 
ON and OFF. 


EXAMPLES 

D QUIT; 

This returns control of execution from an editor layered on VAXTPU to 
the program, application, or operating system that called VAXTPU. If you 
have modified any buffers, you see the following prompt: 

Buffer modifications will not be saved, continue quitting (Y or N)? 

Enter Yes if you want to quit and not save the modifications. Enter No if 
you want to return to the editor. 

g QUIT (OFF) 

This returns control of execution from em editor layered on VAXTPU to the 
program, application, or operating system that called VAXTPU. VAXTPU 
does not alert you if you have modified buffers. All modifications since the 
last time you wrote out the buffer are discarded. 

g PROCEDURE user_quit 

SET (SUCCESS, OFF); 

QUIT; 

! Turn message back on in case user answers "No” to the 
! prompt "Buffer modifications will not be saved, continue 
! quitting (Y or N)?" 

SET (SUCCESS, ON); 

ENDPROCEDURE; 


This procedure turns off the display of the success message, “Editor 
successfully quitting”, when you use the built-in procedure QUIT to leave 
an editing interface. 
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READ CHAR 



Stores the next character entered from the keyboard in a string variable. 

FORMAT 

string := READ_CHAR 

PARAMETERS 

None. 

return value 

A variable of type string containing a character entered from the keyboard. 

DESCRIPTION 

The character read by READ_CHAR is not echoed on the screen; therefore, 
the cursor position does not move. 

READ_CHAR does not process escape sequences. If a VAXTPU procedure 
uses REAI)_CHAR for an escape sequence, only part of the escape 
sequence is read. The remaining part of the escape sequence is treated 
as text characters. If control then returns to VAXTPU, or a READ_ 

KEY or READ_LINE built-in procedure is executed, the results may be 
unpredictable. 

In DECwindows VAXTPU, READ_CHAR maps the main window if it is 
not already mapped. 

In the DECwindows environment, READ_CHAR cannot read a keypad or 
function key. If a VAXTPU procedure uses READ_CHAR and you press a 
keypad or function key, READ_CHAR returns a null string and signals the 
warning TPU$_NOCHARREAD. 

If you invoke VAXTPU with the /NODISPIAY qualifier, do not use READ_ 
CHAR during the session. READ CHAR causes VAXTPU to abort when 
VAXTPU is running in NODISPLAY mode. 

SIGNALED 

ERRORS 

TPU$_NOCHARREAD WARNING READ_CHAR did not read a 

character. 

TPU$_NEEDTOASSIGN ERROR READ_CHAR must be on the 

right-hand side of an assignment 
statement. 

TPU$_TOOMANY ERROR READ_CHAR takes no arguments. 


EXAMPLES 

Q new_char := READ_CHAR 

This assignment statement stores the next character that is entered on 
the keyboard in the string new_char. 


7-293 















VAXTPU Built-In Procedures 

READ CHAR 


PROCEDURE user_quote 

COPY_TEXT (READ_CHAR); 

ENDPROCEDURE; 

This procedure enters the next character that is entered from the keyboard 
in the current buffer. If a key that sends an escape sequence is pressed, 
the first character of the escape sequence is copied into the buffer. 
Subsequent keystrokes are interpreted as self-inserting characters, defined 
keys, or undefined keys, as appropriate. 



7-294 









VAXTPU Built-In Procedures 

READ CUPBOARD 


READ_CLIPBOARD 

Reads string format data from the clipboard and copies it into the current 
buffer, at the editing point, using the buffer’s current text mode (insert or 
overstrike). 

FORMAT 

[ Kecihed I == "EAD.CUPBOARD 

return value 

A range containing the text copied into the current buffer, or an 
unspecified data type indicating that no data was obtained from the 
clipboard. 

DESCRIPTION 

If VAXTPU finds a line-feed character in the data, it removes the hne feed 
and any adjacent carriage returns and puts the data after the line feed on 
the next line of the buffer. If VAXTPU must truncate the data from the 
clipboard, VAXTPU copies the truncated text into the current buffer. 

All text read from the clipboard is copied into the buffer starting at the 
editing point. If VAXTPU must start a new line to fit all the text into the 
buffer, the new line starts at column 1, even if the current left margin is 
not set at column 1. 


SIGNALED 

ERRORS 


TPU$_CLlPBOARDLOCKED 

WARNING 

VAXTPU cannot read from the 
clipboard because some other 
application has locked it. 

TPU$_CLIPBOARDNODATA 

WARNING 

There is no string format data in 
the clipboard. 

TPU$_CLIPBOARDFAIL 

WARNING 

The clipboard has not returned 
any data. 

TPU$_REQUIRESDECW 

ERROR 

You can use the READ_ 
CLIPBOARD built-in only if you 
are using DECwindows TPU. 

TPU$_STRTOOLARGE 

ERROR 

The amount of data in the 
clipboard exceeds 65,535 
characters. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the READ_CLIPBOARD built-in. 
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EXAMPLE 


PROCEDURE eve$$insert__clipboard 
ON_ERROR 

[TPU$_CLIPBOARDNODATA]: 

eve$message (EVE$_NOINSUSESEL); 
eve $1ea rn_abort; 

RETURN (FALSE); 
[TPU$_CLIPBOARDLOCKED]: 

eve$message (EVE$_CLIPBDREADLOCK); 
eve $1ea rn_abort; 

RETURN (FALSE); 

[TPU$_TRUNCATE]: 

[OTHERWISE]: 

eve$learn_abort; 

ENDON ERROR; 


This statement using 
READ_CLIPBOARD reads 
data from the clipboard 
and copies it into the 
current buffer. 


eve $ 1 e a r n__abo rt; 
RETURN (FALSE); 

ENDPROCEDURE; 


IF eve$test_if_modifiable (CURRENT_BUFFER) 
THEN 

READ_CLIPBOARD; ! 

I 

I 

I 

I 

RETURN (TRUE); 

ENDIF; 


This procedure shows one possible way that an application can use the 
READ_CLIPBOARD built-in. This procedure is a modified version of the 
EVE procedure EVE$$INSERT_CLIPBOARD. You can find the original 
version in SYS$EXAMPLES:EVE$DECWINDOWS.TPU. 

Procedure EVE$$INSERT_CLIPBOARD fetches the contents of the 
clipboard £ind places them in the current buffer. 
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READ_FILE 

Reads a file and inserts the contents of the file immediately before the current 
line in the current buffer. READ_FILE optionally returns a string containing the 
file specification of the file read. 

FORMAT 

[string2 := ] READ_FILE (stringl) 

PARAMETER 

String 1 

A quoted string, a variable name representing a string constant, or an 
expression that evaluates to a string, that is the name of the file you want 
to read and include in the current buffer. 

return value 

A string that is the specification of the file read. 

DESCRIPTION 

If the current buffer is mapped to a visible window, the READ_FILE built- 
in causes the screen manager to synchronize the editing point, which is a 
buffer location, with the cursor position, which is a window location. This 
may result in the insertion of padding spaces or lines into the buffer if the 
cursor position is before the beginning of a line, in the middle of a tab, 
beyond the end of a line, or after the last line in the buffer. 

VAXTPU writes a message indicating how many records (lines) were read. 

If you try to read a file containing lines longer than 32767 characters, 
VAXTPU truncates the line to the first 32767 characters and issues a 
warning. 


SIGNALED 

ERRORS 


TPU$_NOCURRENTBUF 

WARNING 

You are not positioned in a buffer. 

TPU$_CONTROLC 

ERROR 

The execution of the read 
terminated because you pressed 
CTRUC. 

TPU$_NOCACHE 

ERROR 

There is not enough memory to 
allocate a new cache. 

TPU$_TOOFEW 

ERROR 

READ_FILE requires at least one 
parameter. 

TPU$_TOOMANY 

ERROR 

READ_FILE accepts no more than 
one parameter. 

TPU$JNVPARAM 

ERROR 

The parameter to READ_FILE 
must be a string. 

TPU$_TRUNCATE 

WARNING 

One of the lines in the file was too 
long to fit in a VAXTPU buffer. 
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The following errors, warnings, and messages can be signaled by 
VAXTPU’s file I/O routine. You can provide your own file I/O routine 
by using VAXTPU’s callable interface. If you do so, READ_FILE’s 
signaled errors, warnings, and messages depend upon what status you 
signaled in your file I/O routine. 

ERROR READ_FILE could not open the 
file you specified. 

ERROR READ_F1LE did not finish reading 
the file because it encountered a 
file system error. 

ERROR READ_FILE did not finish closing 
the file because it encountered a 
file system error. 

EXAMPLES 

D READ_FILE ("login.com") 

T his statement reads the file LOGIN.COM and adds it to your current 
buffer. 

§ PROCEDURE user_two_windows 

w := CREATE_WINDOW (1, 10, ON); 
b := CREATE_BUFFER ("buf2"); 

MAP (w, b) ; 

READ_FILE (READ_LINE ("Enter file name for 2nd window : ")); 

POSITION (BEGINNING_OF (b)); 

DEFINE_KEY ("POSITION (w)", KEY_NAME ("W", SHIFT_KEY)); 

ENDPROCEDURE; 

This procedure creates a second window and a second buffer and maps 
the window to the screen. The procedure also prompts the user for a file 
name to include in the buffer and defines the key sequence SHIFT/W as 
the sequence with which to move to the second window. (The default shift 
key is PFl.) 


TPU$_OPENIN 

TPU$_READERR 

TPU$_CLOSEIN 
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READ GLOBAL SELECT 



Requests information about the specified global selection from the owner of 
the global selection. If the owner provides the information, READ_GLOBAL_ 
SELECT reads it and copies it into the current buffer at the editing point, using 
the buffer’s current text mode (insert or overstrike). The READ_GLOBAL_ 
SELECT built-in also puts line breaks in the text copied into the buffer. 

FORMAT 

,{ unsullied K, „SAD_GLOBAL_SELECT ([’’sectary 1 

’ 1 selection_name J 

selectionjproperty_name) 

PARAMETERS 

PRIMARY 

A keyword indicating that the application is requesting information about 
a property of the primary global selection. 

SECONDARY 

A keyword indicating that the application is requesting information about 
a property of the secondary global selection. 

selection_name 

A string identifying the global selection whose property is the subject of 
the application’s information request. Specify the selection name as a 
string if the layered application needs information about a selection other 
than the primary or secondary global selection. 

selection_property_name 

A string specifying the property whose value the application is requesting. 

return value 

unspecified A data type indicating that the information requested by the 

application was not available. 

•'^rige A range containing the text copied into the current buffer. 

DESCRIPTION 

Use READ_GLOBAL_SELECT to ask the application that owns the 
specified global selection for information about a property of the global 
selection. For example, you can ask about the global selection’s font, the 
number of lines it contains, or the string-formatted data it contains, if any. 

All text read from the global selection is copied into the current buffer 
starting at the editing point. If VAXTPU must start a new line to fit all 
the text into the buffer, the new line starts at column 1, even if the current 
left margin is not set at column 1. 
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If the global selection information requested is an integer, the built-in 
converts the integer into a string before copying it into the current buffer. 
If the information requested is a string, the built-in copies the string into 
the buffer, replacing any hne feeds with line breaks. Carriage returns 
adjacent to line feeds are not copied into the buffer. 


SIGNALED 

ERRORS 


TPU$_BADKEY 

WARNING 

You specified an invalid keyword 
as a parameter. 

TPU$_GBLSELOWNER 

WARNING 

VAXTPU owns the global 
selection. 

TPU$JNVGBLSELDATA 

WARNING 

The global selection owner 
provided data that VAXTPU cannot 
process. 

TPU$_NOGBLSELDATA 

WARNING 

The global selection owner has 
indicated that it cannot provide the 
information requested. 

TPU$_NOGBLSELOWNER 

WARNING 

You have requested Information 
about an unowned global 
selection. 

TPU$_TIMEOUT 

WARNING 

The global selection owner did not 
respond before the timeout period 
expired. 

TPU$_ARGMISMATCH 

ERROR 

Wrong type of data sent to the 
READ_GLOBAL_SELECT built-in. 

TPU$_REQUIRESDECW 

ERROR 

You can use the READ_GLOBAL_ 
SELECT built-in only if you are 
using DECwindows VAXTPU. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
READ_GLOBAL_SELECT built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the READ_GLOBAL_SELECT 
built-in. 


EXAMPLE 


READ_GLOBAL_SELECTION (PRIMARY, "STRING"); 

This statement reads the string-formatted contents of the primary global 
selection and copies it into the current buffer at the current location. 

For another example of code using the READ_GLOBAL_SELECT built-in, 
see Exeimple B-9. 
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READ KEY 



Waits for you to press a key and then returns the key name for that key. 

FORMAT 

keyword := READ_KEY 

PARAMETERS 

None. 

return value 

A key name for the key just pressed. 

DESCRIPTION 

The READ__KEY built-in procedure should be used rather than READ_ 
CHAR when you are entering escape sequences, control characters, or 
any characters other than text characters. READ_KEY processes escape 
sequences and VAXTPlTs shift key (PFl by default). 

The key that is read by READ_KEY is not echoed on the terminal screen. 

In DECwindows VAXTPU, READ^KEY maps the main window if it is not 
already mapped. 

If you invoke VAXTPU with the /NODISPLAY qualifier, do not use READ_ 
KEY during the session. READ^KEY causes VAXTPU to abort when 
VAXTPU is running in NODISPLAY mode. 

SIGNALED 

ERRORS 

TPU$_NEEDTOASSIGN ERROR READ_KEY must be on the 

right-hand side of an assignment 
statement. 

TPU$_TOOMANY ERROR READ_KEY accepts no 

arguments. 

TPU$_CONTROLC ERROR You pressed CTRL/C during the 

execution of READ_KEY. 

TPU$_REQUIRESTERM ERROR You cannot use READ KEY when 

VAXTPU is in NODISPLAY mode. 


EXAMPLES 

Q my_key := READ_KEY 

This assignment statement reads the next key that is entered and stores 
the ke3word for that key in the variable myjtey. 
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PROCEDURE user_help_on_key 

LOCAL key_pressed, 
key_comment; 

MESSAGE ("Press the key you want help on."); 
key__pressed := READ_KEY; 

key__comment := LOOKUP_KEY (key_pressed, COMMENT); 

IF key_comment = 0 
THEN 

MESSAGE ("That key is not defined."); 

ELSE 

IF key_comment = "" 

THEN 

MESSAGE ("There is no comment for that key."); 

ELSE 

MESSAGE (key_comment); 

ENDIF; 

ENDIF; 

ENDPROCEDURE; 

This procedure looks in the current key map list for the next key pressed. 
If the key is found, any comment associated with that key is put into the 
message buffer. 
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READ LINE 



Displays the text that you specify as a prompt for input and reads the 
information entered in response to the prompt. You can optionally specify 
the maximum number of characters to be read. READ_LINE returns a string 
that holds the data that is entered in response to the prompt. 

FORMAT 

string2 := READ_LiNE [ (stringl [ .integer] ) ] 

PARAMETERS 

stringl 

A quoted string, a variable name representing a string constant, or an 
expression that evaluates to a string, that is the text used as a prompt for 
input. This parameter is optional. 

integer 

The integer value that indicates how many characters to read from the 
input entered in response to the prompt. The maximum number is 132. 
This parameter is optional. If not present, control of execution passes from 
READ_LINE to VAXTPU’s main loop when the user presses RETURN, 
CTRL/Z, or the one hundred thirty-second character. 

return value 

A string storing the user’s response to a prompt. 

DESCRIPTION 

The terminators for READ_LINE are the standard VMS terminators 
such as CTRL/Z and RETURN. READ_LINE is not affected by VAXTPU 
key definitions; the built-in teikes literally all keys except standard VMS 
terminators. 

By default, the text you specify as a prompt is written in the prompt area 
on the screen. The prompt area is established with the built-in procedure 
SET (PROMPT_AREA). See SET (PROMPT.AREA) for more information. 
If no prompt area is defined, the text specified as a prompt is displayed at 
the current location on the device pointed to by SYS$OUTPUT (usually 
your terminal). 

If READ_LINE terminates because it reaches the limit of characters 
specified as the second parameter, the last character read becomes the 
last key. Example 2 is a procedure that tests for the last key entered in a 
prompt string. 

In DECwindows VAXTPU, READ_LINE maps the main widget if it is not 
already mapped. 

When you invoke VAXTPU with the /NODISPLAY qualifier, terminal 
functions such as screen display and key definitions are not used. The 
built-in procedure READ_LINE calls the LIB$GET_INPUT routine to 
issue a prompt to SYS$INPUT and accept input from the user. A read 
done this way does not terminate when the number of keys you specified 
as the second parameter {integer) are entered. However, string2 contains 
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the number of characters specified by the integer parameter and LAST_ 
KEY contains the value of the key that corresponds to the integer specified 
as the last key to be read, except in the following cases. If the read is 
terminated by CTRL/Z, LAST_KEY has the v^due CTRL/Z. If the read 
is terminated by a carriage return before the specified integer limit is 
reached, LAST.KEY has the value of the RETURN key. 


SIGNALED 

ERRORS 


TPU$_NEEDTOASSIGN 

ERROR 

TPU$_TOOMANY 

ERROR 

TPU$JNVPARAM 

ERROR 


READ_L1NE must appear on the 
right-hand side of an assignment 
statement. 

READ_LINE accepts no more than 
two arguments. 

One of the arguments to READ_ 
LINE has the wrong data type. 


EXAMPLES 

D my_prompt := READ_LINE ("Enter key definition:", 1) 

This assignment statement displays the text "Enter key definition:" in the 
prompt area, and stores the first character of the user’s response in the 
variable my_prompt. 

g PROCEDURE user__test_lastkey 

LOCAL my_key, 
k; 

my_input := READ_LINE ("Enter 3 characters:", 3); 

! Press the keys "ABC" 

my_key := LAST_KEY; 

IF my_key = KEY_NAME ("C") 

THEN 

MESSAGE (" C key "); 

ELSE 

MESSAGE (" Error "); 

ENDIF; 

ENDPROCEDURE; 


This procedure prompts for three characters and stores them in the 
variable my_input. It then tests for the last key entered. 


Parameters: 

Old integer value - input 
New integer value - output 
Text of prompt - input 

Message printed if user hits RETURN to 
get out of the command - input 

PROCEDURE user_prompt__number (old_number, new__number, 

promptest ring, no__value_message) 

! String read after prompt 


old__number 
new_number 
prompt_st ring 
no_va1ue_me s s age 


LOCAL read_line_string; 
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new_number := old_number; 

IF old_number < 0 
THEN 

read_line_string := READ_LINE (promptestring); 

EDIT (read_line__string, TRIM) / 

IF read_line_string = " 

THEN 

MESSAGE (no_value_message); 
new_number ;= 0; 

RETURN (0); 

ELSE 

! Change lowercase 1 to #1 
TRANSLATE (read_line_string, "1", "1"); 
new_number := INT (read_line_string); 

IF (new_number = 0) and (read_line_string <> "0") 

THEN 

MESSAGE (FAO ("Don't understand !AS", 
read_line_string)); 

RETURN (0); 

ELSE 

RETURN (1); 

ENDIF; 

ENDIF; 

ELSE 

RETURN (1) ; 

ENDIF; 

ENDPROCEDURE; 

This procedure is used by commands that prompt for integers. The 
procedure returns true if prompting worked or was not needed; it 
returns false otherwise. The returned value is passed back as an output 
parameter. 
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REALIZE WIDGET 



Creates a window for the specified widget instance and maps the window to 
the display. 

FORMAT 

REALIZE_WIDGET (widget) 

PARAMETER 

widget 

The widget instance you want VAXTPU to realize. 

DESCRIPTION 

Note that you can realize a widget only once during the widget’s lifetime. 
For more information on realizing widgets, see the VMS DECwindows 
Guide to Application Programming and the VMS DECwindows Toolkit 
Routines Reference Manual. 

SIGNALED 

ERRORS 

TPU$_NEEDTOASSIGN ERROR REALIZE_WIDGET must return a 

value. 

TPU$_TOOMANY ERROR Too many arguments specified. 

TPU$_TOOFEW ERROR Too few arguments specified. 

TPU$_INVPARAM ERROR The argument to REALIZE_ 

WIDGET has the wrong data 
type. 

TPU$_REQUIRESDECW ERROR Requires the VAXTPU 

DECwindows screen updater. 


EXAMPLE 

REALIZE_WIDGET (exainple_widget); 

This statement realizes the widget stored in example_widget. 
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RECOVER BUFFER 



Reconstructs the work done in the buffer whose name you specify. VAXTPU 
creates a new buffer using the specified buffer name and, using the 
information in the original buffer’s journal file, recovers all the changes made 
to records in the original file. The resulting recovery is written to the newly 
created buffer. 

FORMAT 

buffer! := RECOVER_BUFFER (stringl | }; 

PARAMETERS 

stringl 

The name of the buffer you are trying to recover. 

string2 

The name of the journal file you want VAXTPU to use to recover your 
buffer. If you did not set a journal file name using SET (JOURNALING), 
in most cases VAXTPU will have created the journal file using its default 
journal file naming algorithm. If the journal file was named by default, 
you need not specify a journal file name with RECOVER_BUFFER. If you 
specified a journal file name using SET (JOURNALING), use the same 
name with RECOVER_BUFFER. 

Do not specify any directory name in this string. Specify only the buffer 
name and the extension, if any. 

buffer2 

The buffer whose attributes you want appUed to the newly created buffer. 
For more information on using a buffer as a template, see the description 
of the CREATE_BUFFER built-in. 

return value 

The buffer containing the recovered text. If the recovery failed, an integer 
0 is returned. 

DESCRIPTION 

Do not confuse the RECOVER_BUFFER built-in with the /RECOVER 
command qualifier in DCL. /RECOVER is used when invoking VAXTPU 
to recover a session or buffer. RECOVER_BUFFER, on the other hand, is 
used after VAXTPU has been invoked. It uses a buffer change journal file 
to recover the changes made to a specified buffer. 

Note that RECOVER_BUFFER works on with buffer change journaling; 
you cannot recover a keystroke journal file with RECOVER_BUFFER. 

Only the first parameter (the old buffer name) is required. If you weuit to 
specify the third parameter but not the second, you must use a comma as 
a placeholder, as follows: 

RECOVER_BUFFER ("junk.txt", , template_buffer); 

The third parameter is optional. 
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If VAXTPU returns a message that it cannot find the journal file and if the 
buffer you are tr 5 dng to recover is small, the reason for the message might 
be that changes to the buffer were never written to the journal file because 
there were not enough changes to trigger the first write operation to the 
journal file. Similarly, if some text is missing after recovery, the reason 
might be that the last few changes did not trigger a write operation. For 
more information on how VAXTPU manages write operations to a journal 
file, see the description of the SET (JOURNALING) built-in. 

Buffer change joumahng does not journal changes in buffer attributes 
(such as modifiability of the buffer or visibility of tabs). Buffer change 
journaling only tracks changes to records in the buffer, such as addition, 
deletion, or modification of a record or changes in a record’s attributes. 

If you press CTRL/C during a recovery, VAXTPU terminates the recovery, 
closes the journal file, and deletes the newly created buffer. 

If possible, after a successful recovery, VAXTPU continues journaling new 
changes into the journal file that was used during the recovery. However, 
it is likely that the journal file contains partial records at the end. In this 
case, VAXTPU cannot continue journaling to the same file. VAXTPU closes 
the journal file, marks the buffer unsafe for journaling, and signals an 
error. 

If you have journal files created with the default naming algorithm as 
a result of editing multiple buffers with the same or similar names, 
RECOVER_BUFFER might not recover the buffer you intend. For more 
information on the default journal file naming algorithm, see Section 1.7.1. 
For example, suppose you were editing two buffers, one called TEST! and 
the other called TEST?. The default journal file naming algorithm creates 
for each buffer a journal file named TEST_.TPU$JOURNAL. The journal 
file for the buffer created first has the lower version number. If there 
were a system interruption while you were editing both buffers, and if the 
journal file for TEST! had the lower version number, then RECOVER_ 
BUFFER would recover the journal file created for the buffer TEST?. 

When you write the contents of a buffer to a file, VAXTPU erases the 
journal file. If you write the contents of the buffer to a file other than the 
default output file, the journal file contains a pointer to the file to which 
you last wrote the buffer. For example, if the buffer is called MAIN but 
you write the contents of the buffer to a file called OPUS.TXT, the journal 
file contains a pointer to the file OPUS.TXT. OPUS.TXT is known as the 
"source file" because, during a recovery VAXTPU uses OPUS.TXT as the 
source for the contents of the buffer as they were when the write operation 
was performed. 

Caution: Since journal files often point to a source file that is not the same 
as the file originally read into the buffer, if you delete the source 
file, the buffer will be unrecoverable. 

Similarly, if you have changed the name of the original file 
required for a recovery, the buffer will be unrecoverable. VAXTPU 
prompts for a new file name if it cannot find the original file. Be 
careful to specify the correct file name in this case. 
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SIGNALED 

ERRORS 


TPU$_JRNLNOTSAFE 

WARNING 

The buffer is not safe for 
journaling. 

TPU$_NOTJOURNAL 

ERROR 

The file specified is not a valid 
journal file. 

TPU$_RECOVERABORT 

WARNING 

An inconsistency was found 
between the journal file and the 
currently executing procedure. 
Recovery is aborted and the 
journal file closed. 

TPU$_RECOVERFAIL 

ERROR 

Recovery was terminated 
abnormally due to journal file 
Inconsistency. 

TPU$_RECOVERQUIT 

WARNING 

You did not specify a valid source 
file name. 


EXAMPLES 

D RECOVER_BUFFER ("junk.txt"); 

This statement directs VAXTPU to find the buffer change journal file 
associated with the original buffer JUNKTXT, to create a new buffer 
called JUNKTXT, and, using the information from the journal file, to 
recover the changes made in the original JUNKTXT buffer. The results of 
the recovery are placed in the new JUNKTXT buffer. 

g defaults_buffer := CREATE_BUFFER ("Defaults"); 

SET (EOB_TEST, defaults_buffer, "[That's all, folks!]"); 
user_buffer := CREATE_BUFFER ("Userl.txt", defaults_buffer); 

SET (JOURNALING, user_buffer, ON, "userl_journal.tpu$journal"); 


RECOVER_BUFFER ("Userl.txt", "userl_journal.tpu$journal", 
defaults_buffer); 

This code fragment creates a defaults buffer, changes an attribute of the 
defaults buffer, and creates a user buffer. The fourth statement turns 
on buffer change journaling and designates the file named USER1_ 
JOURNAL.TPU$JOURNAL as the journaling file. At some later point 
in the session (represented by the ellipses) the RECOVER_BUFFER 
statement is used to recover the contents of the old USER1.TXT by using 
the journal file USERl_JOURNAL.TPU$JOURNAL. The attributes of the 
defaults buffer are applied to the newly created buffer USER1.TXT. In this 
case, the new buffer has the end-of-buffer text "[That’s all, folks!]". 
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REFRESH 

Repaints the whole screen. REFRESH erases any extraneous characters, 
such as those caused by noise on a communication line, and repositions the 
text so that the screen represents the last known state of the editing context. 

FORMAT 

REFRESH 

PARAMETERS 

None. 

DESCRIPTION 

REFRESH causes a redrawing of every line of every window that is 
mapped to the screen. The prompt area is erased. This built-in procedure 
causes the screen to change immediately. Even if REFRESH is issued from 
within a procedure, the action takes place immediately; VAXTPU does not 
wait until the entire procedure is completed to execute REFRESH. 

If screen updating is disabled when VAXTPU executes the REFRESH 
command, VAXTPU performs the refresh operation when updating is 
enabled again. 

VAXTPU reissues escape sequences as appropriate to do any of the 
following: 

• To set the width of the terminal 

• To set the scrolling region 

• To set the keypad to applications mode 

• To set the video attributes to a known state 

• To clear the screen of a DIGITAL-supported terminal 

• To reset the nonalphanumeric character sets 

REFRESH repaints the whole screen. See UPDATE for a description of 
how to update a single window to make it reflect the current state of its 
associated buffer. If you want to update every visible window without 
erasing the screen, use the UPDATE (ALL) built-in. 

See Chapter 6 for an explanation of how the screen is updated under 
various circumstances. 

SIGNALED 

ERROR 

TPU$_TOOMANY ERROR REFRESH takes no parameters. 
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EXAMPLES 

Q REFRESH 

This statement causes the screen manager to repaint the whole screen so 
that it reflects the current internal state of the editor. 

g PROCEDURE user_repaint 

ERASE (message__buf fer) ; 

REFRESH; 

ENDPROCEDURE; 


This procedure removes the contents of the message buffer and then 
repaints the whole screen. 
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REMAIN 

Specifies that aii characters from the current position to the end of the line 
should be included in a pattern. 

FORMAT 

REMAIN 

PARAMETERS 

None. 

DESCRIPTION 

When used as part of a complex pattern or as an argument to SEARCH, 
REMAIN matches the rest of the characters on a line. REMAIN matches 
successfully even if there are no more characters on the line. 

Although REMAIN behaves much like a built-in, it is actually a keyword. 

SIGNALED 

ERROR 

REMAIN is a ke 3 rword and has no completion codes. 

EXAMPLES 


Q patl := LINE__BEGIN + "!" + REMAIN 

This assignment statement stores in the variable patl a pattern that 
matches all lines that have an exclamation point at the beginning of the 
line. 

§ PROCEDURE remove^comments 

LOCAL patl, 
here, 

coinment__range; 

here := MARK (NONE); ! Remember our location 
patl := "!" + REMAIN; 

POSITION (BEGINNING_OF (CURRENT__BUFFER) ) ; 

LOOP 

comment_range := SEARCH_QUIETLY (patl, FORWARD); 

EXITIF comment_range = 0; 

ERASE (comment_range); 

POSITION (comment__range) ; 

ENDLOOP; 

POSITION (here); 

ENDPROCEDURE; 


This procedure removes eill comments from the current buffer. It does not 
correctly handle quoted strings containing exclamation points. 
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REMOVE_KEY_MAP 

Removes key maps from key map lists. 

FORMAT 

REMOVE_KEY_MAP (stringl, string2 [, ALL ]) 

PARAMETERS 

String 1 

A quoted string, or a variable name representing a string constant, that 
specifies the name of the key map list containing the key map to be 
removed. 

string2 

A quoted string, or a variable name representing a string constant, that 
specifies the name of the key map to be removed from the key map hst. 

ALL 

This keyword is an optional argument. It specifies that all the key maps 
with the name specified by string2 in the key map hst are to be removed. 

DESCRIPTION 

This built-in procedure removes one or more key maps from a key map 
list. If the optional keyword ALL is specified, all of the key maps with the 
specified name in the key map list are removed from the list. Otherwise, 
only the first entry with the specified name is removed. 


SIGNALED 

ERRORS 


TPU$_NOKEYMAP 

WARNING 

You specified an argument that is 
not a defined key map. 

TPU$_NOKEYMAPLIST 

WARNING 

You specified an argument that is 
not a defined key map list. 

TPU$_KEYMAPNOTFND 

WARNING 

The key map you specified is not 
found. 

TPU$_EMPTYKMLIST 

WARNING 

The key map list you specified 
contains no key maps. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
REMOVE_KEY_MAP built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the REMOVE_KEY_MAP built-in. 

TPU$_INVPARAM 

ERROR 

Wrong type of data sent to the 
REMOVE_KEY_MAP built-in. 
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TPU$__UNKKEYWORD ERROR An unknown keyword has been 

used as an argument. Only the 
keyword ALL is allowed. 

TPLI$_BADKEY ERROR An unknown keyword has been 

used as an argument. Only the 
keyword ALL is allowed. 


EXAMPLE 

user$keymap_l := CREATE_KEY_MAP ("keymap__l"); 
user$keymap_2 ;= CREATE_KEY_MAP ("keymap_2"); 

user$keymap_list := CREATE__KEY_MAP_LIST ("keymap_list”, user$keymap_l, 

user$keymap_2); 

ADD_KEY_MAP (user$keymap__list, "last", user$keymap_l); 


SHOW (KEY_MAP_LISTS); 


REMOVE_KEY_MAP (user$keymap_list, user$keymap_l, ALL); 


SHOW (KEY_MAP_LISTS); 


In this example, a key map list n 2 imed KEYMAP_LIST is created. The call 
to SHOW (KEY_MAP_LISTS) shows that the key map hst contains three 
key maps: KEYMAP_1, KEYMAP_2, and KEYMAP_1 again. After the call 
to REMOVE_KEY_MAP, the call to SHOW (KEY_MAP_LISTS) shows that 
the key map list contains only KEYMAP_2. 
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RETURN 

A VAXTPU language element. It returns control from the current procedure to 
its caller, optionally specifying the value the current procedure returns to the 
caller. 

FORMAT 

RETURN f expression ] 

RETURN is a VAXTPU language element. It does not take parameters. 
However, it is optionally followed by a VAXTPU expression. 

PARAMETERS 

expression 

This expression may be any VAXTPU expression, variable, or built-in. It 
specifies what the current procedure should return to its caller. 

DESCRIPTION 

The RETURN statement returns control from the current procedure to its 
caller. It also provides a value for the current routine. 

RETURN is evaluated for correct syntax at compile time. In contrast, 
VAXTPU procedures are usually evaluated for a correct parameter coimt 
and parameter types at execution time. 

SIGNALED 

ERROR 

RETURN is a language element and signals no errors or warnings. 


EXAMPLES 

Q PROCEDURE user_erase_message_buffer 

IF CURRENT_BUFFER = message_buffer 
THEN 

RETURN; 

ENDIF; 

ERASE (message^buffer) ; 

ENDPROCEDURE; 

This procedure erases the message buffer. If the current buffer is the 
message buffer, it returns without erasing it. 

§ PROCEDURE user_find_string (look_for) 

ON_ERROR 

RETURN "String not found"; 

ENDON_ERROR; 

RETURN SEARCH (look_for, FORWARD); 


ENDPROCEDURE; 

This procedure searches for a string. If it does not find the string, it 
returns the string String not found. Otherwise, it returns the range 
containing the found string. 
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SAVE 

Writes the binary forms of all currently defined procedures, variables, key 
definitions, key maps, and key map lists to the section file you specify. 

FORMAT 

SAVE (string 1 [, ”NO_DEBUG_NAMES"J 

1, ”NO_PROCEDURE_NAMES’'J 
iriDENr, string2]l) 

PARAMETERS 

stringl 

A string that is a valid VMS file specification. If you supply only a file 
name, VAXTPU uses the current device and directory, not necessarily the 
SYS$LOGIN device and directory, in the file specification. 

'•NO_DEBUG_NAMES" 

A string that prevents VAXTPU from writing debugging information to 
the section file. When you use "NO_DEBUG_NAMES", VAXTPU does not 
write procedure parameter names or local variable names. You can reduce 
the size of the section file by specifying this string. Do not specify this 
string if you intend to use the VAXTPU debugger on the section file. 

”NO_PROCEDURE_NAMES’' 

A string, or a variable or constant neune representing this string, that 
prevents VAXTPU from writing procedure names to the section file. You 
can reduce the size of the section file by specifying this string. However, 
the procedure names are required to display a meaningful traceback when 
an error occurs. Therefore, do not specify this string if you want to use 
the application created by the section file with the TRACEBACK or LINE_ 
NUMBER function set to ON. 

’WENT” 

A string specifying that you want to assign an identifying string, such as a 
version number, to the section file. 

string2 

The string (usually a version number) that you want to assign to the 
section file. 

DESCRIPTION 

SAVE is used to create VAXTPU section files. If you are adding to an 
existing section file, the new section file contains all of the items from the 
original section file and the new items from the current editing session. 
Section files enable VAXTPU interfaces to start up quickly because they 
contain the following items in binary form: 

• All compiled PROCEDURE . . . ENDPROCEDURE statements 

• Every variable created (only the variable’s name is saved, not its 
contents) 
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• Every key definition that binds a statement, procedure, program, or 
learn sequence to a key, including the comments that you add to key 
definitions 

• Every key map and key map list created 

• All defined constants 

When you use the built-in procedure SAVE during an editing session to 
add items to an existing section file, SAVE does not keep items that were 
established interactively with the built-in procedure SET (for example, 
margin settings for buffers, or setting the editor’s shift key to something 
other than the PFl key). 

If you do not specify a device and directory in the string parameter, 
VAXTPU uses your current device and directory. 

The default file type is TPU$SECTION. 

When you use the built-in procedure SAVE, informational messages are 
generated for any imdefined procedures or ambiguous symbols as they are 
written to the section file. If the display of informational messages has 
been disabled, these messages are not displayed. 


SIGNALED 

ERRORS 


TPU$_SAVEERROR 

ERROR 

The section cannot be 
created because of 
errors in the context 
being saved. 

TPU$_TOOFEW 

ERROR 

Too few arguments 
passed to the SAVE 
built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments 
passed to the SAVE 
built-in. 

TPU$JNVPARAM 

ERROR 

Wrong type of data sent 
to the SAVE built-in. 

TPU$_SECTUNDEFPROC 

WARNING 

Undefined procedures 
or ambiguous symbols 
were found while the 
section file was being 
written. 

TPU$_BADSYMTAB 

ERROR 

VAXTPU’s symbol 
tables are inconsistent. 

TPU$_SAVEUNDEFPROC 

INFORMATIONAL 

An undefined procedure 
is being written to the 
section file. 

TPU$_SAVEAMBIGSYM 

INFORMATIONAL 

An ambiguous symbol 
is being written to the 
section file. 
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EXAMPLES 

D SAVE (”SYS$LOGIN:mysection.TPU$SECTION") 

This statement, issued just before exiting from the editor, adds all of the 
procedure definitions, key definitions, and variables from your current 
editing session to the section file with which you invoked VAXTPU. The 
new file that you specify, SYS$LOGIN:mysection.TPU$SECTION, contains 
initialization items from the original section file and from your editing 
session. 

To invoke VAXTPU with the new section file, enter the following command 
at the DCL level: 

$ EDIT/TPU/SECTION=sys$login:mysection 

§ PROCEDURE eve_next_paragraph 

LOCAL patl, 

the_range; 

patl := LINE_BEGIN + LINE_BEGIN + ARB (1); 
the_range := SEARCH_QUIETLY (patl, FORWARD, EXACT); 

IF the_range <> 0 
THEN 

POSITION (END_OF (the_range)); 

ENDIF; 

ENDPROCEDURE; 


g PROCEDURE tpu$local__init 
SET (SHIFT_KEY, KPO); 

DEFINE_KEY ("eve___next__paragraph", PERIOD, "Next Para"); 
ENDPROCEDURE; 

SAVE ("my_section", "ident", "VI.5"); 

QUIT; 


These procedures and statements show how SAVE can be used in a 
command file to extend an apphcation. The first procedure moves the 
cursor to the beginning of the next paragraph. The second procedure 
defines a shift key and binds the procedure evejiext_paragraph to the 
period key on the keypad. The SAVE statement directs VAXTPU to 
write the binary form of evejiext_paragraph and the key definition to a 
section file called MY_SECTION.TPU$SECTION. The second and third 
parameters to the SAVE statement direct VAXTPU to assign the string 
’VI.5” to the section file. The QUIT statement terminates the VAXTPU 
session. 
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SCAN 

Returns a pattern that matches only characters that do not appear in the 
string, buffer, or range used as its parameter. SCAN matches as many 
characters as possible. 

FORMAT 

p,«,..scAN 

PARAMETERS 

buffer 

An expression that evaluates to a buffer. SCAN does not match any of the 
characters that appear in the buffer. 

range 

An expression that evaluates to a range. SCAN does not match any of the 
characters that appear in the range. 

string 

An expression that evaluates to a string. SCAN does not match any of the 
characters that appear in the string. 

FORWARD 

A keyword directing VAXTPU to match characters in the forward direction. 
This is the default. 

REVERSE 

A keyword directing VAXTPU to match characters as follows: first, match 
characters in the forward direction until VAXTPU finds a character that 
is a member of the set of characters. Next, return to the first character 
matched and start matching characters in the reverse direction until 
VAXTPU finds a character that is in the set. 

You can specify REVERSE only if you are using SCAN in the first 
element of a pattern being used in a reverse search. In all other contexts, 
specifying REVERSE has no effect. 

The behavior enabled by REVERSE allows an alternate form of reverse 
search. By default, a reverse search stops as soon as a successful match 
occurs, even if there might have been a longer successful match in the 
reverse direction. By specifying REVERSE, you direct VAXTPU not to stop 
matching in either direction until it has matched as many characters as 
possible. 

return value 

A pattern matching only characters that do not appear in the buffer, 
range, or string used as the parameter. 
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DESCRIPTION SCAN matches one or more characters, none of which appear in the 

string, buffer, or range passed as its parameter. SCAN matches as many 
characters as possible, stopping only if it finds a character that is present 
in its parameter or if it reaches the end of a line. If SCAN is part of a 
larger pattern, SCAN does not match a character if doing so prevents the 
rest of the pattern from matching. 

SCAN does not cross line boundaries, lb match a string of characters that 
may cross one or more line boundaries, use SCANL. 


SIGNALED 

ERRORS 

TPU$_NEEDTOASSIGN 

ERROR 

SCAN must appear in the right- 
hand side of an assignment 
statement. 


TPU$_TOOFEW 

ERROR 

SCAN requires at least one 
argument. 


TPU$_TOOMANY 

ERROR 

SCAN accepts no more than one 
argument. 


TPU$_ARGMISMATCH 

ERROR 

SCAN was given an argument of 
the wrong type. 


TPU$_CONTROLC 

ERROR 

You pressed CTRUC during the 
execution of SCAN. 


EXAMPLES 

D patl := SCAN ("abc") 

This assignment statement stores a pattern that matches the longest 
string of characters that does not contain a, b, or c in patl, 

§ PROCEDURE user_find_parens 

paren__text : = ANY (" (') + SCAN (')"); 

found_range := SEARCH (paren_text, FORWARD, NONEXACT); 

IF found_range =0 ! No parentheses. 

THEN 

MESSAGE ("No parentheses found."); 

ELSE 

POSITION (found_range); 

ENDIF; 

ENDPROCEDURE; 

This procedure identifies parenthesized text within a single line. It moves 
the editing point to the beginning of the parenthesized text, if it is foimd. 
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PROCEDURE user_remove_odd_characters 
LOCAL patl, 

odd_text; 

patl := SCAN ("abcdefghijklmnopqrstuvwxyz 0123456789"); 
POSITION (BEGINNING_OF (CURRENT_BUFFER)); 

LOOP 

odd_text := SEARCH_QUIETLY (patl, FORWARD); 

EXITIF odd_text = 0; 

ERASE (odd_text); 

POSITION (odd_text); 

ENDLOOP; 

POSITION (END_OF (CURRENT_BUFFER)); 

ENDPROCEDURE; 


This procedure goes through the current file, deleting all characters that 
are not numbers, letters, or spaces. 

Q word := SCAN (' REVERSE); 

This statement defines the variable word to mean the longest consecutive 
string of characters that does not include a space character. Suppose you 
are searching the text Xanadu, the cursor is on the n, and you use the 
following statement: 

tlie_range := SEARCH (word, REVERSE); 

The variable the_range contains the word Xanadu. The reason for this 
is when you use SCAN with REVERSE as the first element of a pattern, 
and then use that pattern in a reverse search, SCAN matches as many 
characters as possible in both the forward and reverse directions. 

Suppose that the cursor is on the n of Xanadu, as before, but you define 
the variable word without the REVERSE ke 3 nvord, as follows: 

word := SCAN (' '); 

If you do a reverse search, the_range contains the characters nadu. 
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SCANL 

Returns a pattern matching a string of characters, including line breaks, none 
of which appear in the buffer, range, or string used as its parameter. The 
returned pattern contains as many characters and line breaks as possible. 

FORMAT 

p«tern := SCANL ({«£}/•{ } J) 

PARAMETERS 

buffer 

An expression that evaluates to a buffer. SCANL does not match any of 
the characters that appear in the buffer. 

range 

An expression that evaluates to a range. SCANL does not match any of 
the characters that appear in the range. 

String 

An expression that evaluates to a string. SCANL does not match any of 
the characters that appear in the string. 

FORWARD 

A keyword directing VAXTPU to match characters in the forward direction. 
This is the default. 

REVERSE 

A keyword directing VAXTPU to match characters as follows: first, match 
characters in the forward direction until VAXTPU finds a character that 
is a member of the set of characters. Next, return to the first character 
matched and start matching characters in the reverse direction until 
VAXTPU finds a character that is in the set. 

You can specify REVERSE only if you are using SCANL in the first 
element of a pattern being used in a reverse search. In all other contexts, 
specifying REVERSE has no effect. 

The behavior enabled by REVERSE allows an alternate form of reverse 
search. By default, a reverse search stops as soon as a successful match 
occurs, even if there might have been a longer successful match in the 
reverse direction. By specifying REVERSE, you direct VAXTPU not to stop 
matching in either direction until it has matched as many characters as 
possible. 

return value 

A pattern that may contain line breaks and that matches only characters 
that do not appear in the buffer, range, or string used as the parameter. 
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DESCRIPTION SCANL is similar to SCAN in that it matches one or more characters that 

do not appear in the string, buffer, or range used as its parameter. Unlike 
SCAN, however, SCANL does not stop matching when it reaches the end 
of a line. Rather, it successfully matches the line end and continues trying 
to match characters on the next line. If SCANL is part of a larger pattern, 
it does not match a character or line boimdary if doing so prevents the rest 
of the pattern from matching. 

SCANL must match at least one character. 


SIGNALED 

ERRORS 


TPU$_NEEDTOASSIGN 

ERROR 

SCANL must appear in the right- 
hand side of an assignment 
statement. 

TPU$_TOOFEW 

ERROR 

SCANL requires at least one 
argument. 

TPU$_TOOMANY 

ERROR 

SCANL requires no more than one 
argument. 

TPU$_ARGMISMATCH 

ERROR 

Argument to SCANL has the 
wrong type. 

TPU$_CONTROLC 

ERROR 

You pressed CTRL/C during the 
execution of SCANL. 


EXAMPLES 

D sentence_pattern := any ("ABCDEFGHIJKLMNOPQRSTUVWXYZ”) + scanl (".!?); 


This assignment statement creates a pattern that matches a sentence. It 
assumes that a sentence ends in one of the following characters: a period 
(.), an exclamation point (!), or a question mark (?). The matched text 
does not include the punctuation mark ending the sentence. 

PROCEDURE user_remove_non_numbers 
LOCAL patl, 

non_number_region; 

patl := SCANL ("0123456789"); 

POSITION (BEGINNING_OF (CURRENT_BUFFER)); 

LOOP 

non_number_region SEARCH_QUIETLY (patl, FORWARD); 

EXITIF non_number_region = 0; 

ERASE (non_number_region); 

POSITION (non_number_region); 

ENDLOOP; 

POSITION (BEGINNING_OF (CURRENT_BUFFER)); 

ENDPROCEDURE; 

This procedure goes through the current buffer erasing anything that is 
not a number. The only line breaks it leaves in the file are those between 
a line ending with a number and one beginning with a number. 
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SCROLL 

Moves the lines of text in the buffer up or down on the screen by the number 
of lines you specify. 

FORMAT 

[Integer2 := ]SCROLL (window [,integer1]) 

PARAMETERS 

window 

The window associated with the buffer whose text you want to scroll. 

integerl 

The signed integer value that indicates how many lines you want the text 
to scroll. If you supply a negative value for the second parameter, the 
lines of text scroll off the top of the screen, leaving the cursor closer to 
the beginning of the buffer. If you supply a positive value for the second 
parameter, the lines of text scroll off the bottom of the screen, leaving the 
cursor closer to the end of the buffer. If you specify 0 as the integer value, 
no scrolling occurs. 

This parameter is optional. If you omit the second parameter, the text 
scrolls continuously until it reaches a buffer boimdary or until you press 
a key. If the current direction of the buffer is forward, the text scrolls 
to the end of the buffer. If the current direction of the buffer is reverse, 
the text scrolls to the beginning of the buffer. If you press a key that 
has commands bound to it, the scrolling stops and VAXTPU executes the 
commands bound to the key. 

return value 

An integer indicating the number and direction of lines actually scrolled 
as a result of using SCROLL. 

DESCRIPTION 

You can scroll text only in a visible window. If the window is not currently 
visible on the screen, VAXTPU issues an error message. 

During scrolling, the cursor does not move but stays positioned at the 
same relative screen location. The current editing point is different from 
the editing point that was current before you issued the SCROLL built-in. 

SCROLL optionally returns an integer that indicates the number and 
direction of lines actually scrolled. If you supply a negative value for the 
second parameter, the lines of text scroll off the bottom of the screen, 
leaving the cursor closer to the beginning of the buffer. If you supply a 
positive value for the second parameter, the lines of text scroll off the top 
of the screen, leaving the cursor closer to the end of the buffer. The value 
of integer2 may differ from what was specified in integerl. 

Note that SCROLL causes the screen to scroll immediately. It does not 
wait to take effect for the completion of a procedure. 

If the buffer has been modified or the window display has altered since the 
last update, the window is updated before the scrolling operation begins. 
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SCROLL does not work in the following cases: 

• If you have turned off the screen update flag with SET (SCREEN^ 
UPDATE, OFF) 

• If you used the /NODISPLAY qualifier when invoking VAXTPU on an 
unsupported device 

• If the window that you specify is not visible on the screen 

When the scrolling is complete, the editing point (record and offset) is set 
to match the cursor position (screen line and column position). 

After the scrolling stops, the cursor may be located to the right of the 
last character in the new current record, to the left of the left margin, or 
in the middle of a tab. In this instance, any VAXTPU built-in procedure 
that requires a record offset (for example, CURRENT_OFFSET, MOVE_ 
HORIZONTAL, MOVE_VERTICAL, MARK, and so on) causes the record 
to be blank-padded to the cursor location. 

If the screen you are using does not have hardware scrolling regions, 
the window being scrolled is repainted for each scroll that would have 
occurred. For instance, the statement SCROLL (my_window,3) repaints 
the window three times. 

If you use SCROLL while positioned after the end of the buffer, SCROLL 
completes successfully and returns 0 as the amount scrolled. 


SIGNALED 

ERRORS 

TPU$_CONTROLC 

ERROR 

You pressed CTRUC to stop 
scrolling. 


TPU$_WINDNOTMAPPED 

WARNING 

You are trying to scroll an 
unmapped window. 


TPU$_TOOFEW 

ERROR 

SCROLL requires at least one 
parameter. 


TPU$_TOOMANY 

ERROR 

You specified more than two 
parameters. 


TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 


EXAMPLES 

D SCROLL (main_window,+10) 

This statement causes the text of the buffer that is mapped to the main 
window to scroll forward 10 lines. 

§ SCROLL (my_window) 

This statement causes the text in the buffer that is mapped to myjvindow 
to scroll in the direction that the buffer is set to until it reaches a buffer 
boundary or the user presses any key. 
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g PROCEDURE user_scroll_buffer 
LOCAL scrolled__lines; 

MESSAGE ("Press any key to stop scrolling..."); 
scrolled_lines := SCROLL (main_window); 
duinmy_key := READ_KEY; 

RETURN scrolled_lines; 

ENDPROCEDURE; 


This procedure scrolls the main buffer until the user presses a key. The 
procedure returns the number of lines scrolled. 
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SEARCH 

Looks for a particular arrangement of characters in a buffer or range and 
returns a range that contains those characters. 


FORMAT 


[range2 := JSEARCH 


f FORWARD \ jr 
I REVERSE J 


( ANCHOR 
BUFFER_BEGIN 
BUFFER_END 
LINE_BEGIN 
J UNEJEND 
' 1 PAGE_BREAK 


pattern 

REMAIN 


string 

I UNANCHOR 
EXACT 
NO_EXACT 
integer 



buffer 
range 1 



PARAMETERS ANCHOR 

A ke 3 rword directing SEARCH to start a search at the current character 
position. Use this ke 5 nvord as part of a complex pattern. 

BUFFER_BEGIN 

A keyword used to match the beginning of a buffer. 

BUFFER_END 

A ke 5 rword used to match the end of a buffer. 

LINE_BEGIN 

A keyword used to match the beginning of a hne. 

UNE_END 

A keyword used to match the end of a line. 

PAGE_BREAK 

A keyword used to match a form-feed character. 

pattern 

The pattern that you want to match. 

REMAIN 

A keyword specifying a match starting at the current character and 
continuing to the end of the current line. 

String 

The string that you want to match. 
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UNANCHOR 

A keyword specifying that the next pattern element can match an 3 where 
after the previous pattern element. Use this keyword as part of a complex 
pattern. 

For more information on these keywords, refer to the individual 
descriptions of them in this chapter. 

FORWARD 

Indicates a search in the forward direction. 

REVERSE 

Indicates a search in the reverse direction. 

EXACT 

Indicates that the characters SEARCH is tr 3 dng to match must be the 
same case and have the same diacritical markings as those in the string 
or pattern used as the first parameter to SEARCH. 

NO_EXACT 

Indicates that the characters SEARCH is trying to match need not be the 
same case nor have the same diacritical markings as those in the string or 
pattern used as the first parameter to SEARCH. NO_EXACT is the default 
value for the optional third parameter. 

integer 

Specifies how SEARCH should handle case and diacritical information 
if you want to match one attribute and ignore the other. DIGITAL 
recommends that you use the defined consteuits available for specifying 
this integer. The defined constants are as follows: 

• TPU$K_SEARCH_CASE — Equivalent to the integer 1. This specifies 
that the search should match the case of the first parameter but be 
insensitive to the diacritical markings of the first parameter. 

• TPU$K_SEARCH_DIACRITICAL — Equivalent to the integer 2. This 
specifies that the search should match the diacritical markings of the 
first parameter but be insensitive to the case of the first parameter. 

buffer 

The buffer in which to search. SEARCH starts at the beginning of the 
buffer when doing a forward search and at the end of the buffer when 
doing a reverse search. 

rangel 

The range in which to search. SEARCH starts at the beginning of the 
range when doing a forward search and at the end of the range when 
doing a reverse search. 

To search a range for all occurrences of a pattern, you must define the 
range d 3 niamically after each successful match. Otherwise, SEARCH 
positions to the beginning of the range and finds the same occurrence over 
and over. See the example section for a procedure that searches for all 
occurrences of a pattern in a range. 
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rsturn valU6 The range containing characters that match the pattern or string specified 

as a parameter. 


[)£3QP|PY|Q^ SEARCH looks for text that matches the string, pattern, or keyword 

specified as its first parameter. If it finds such text, it creates a range 
containing this text and returns it. If SEARCH does not find a match, 
SEARCH returns 0 and signals the error TPU$_STRNOTFOUND. To 
perform a search that does not signal an error when there is no match, use 
the SEARCH.QUIETLY built-in. 

The starting position for the search depends on the optional fourth 
parameter and the search direction. If you do not specify the fourth 
parameter, the search starts at the editing point. 

If you specify a range for the fourth parameter, the search starts at the 
beginning of the range for a forward search, or the end of the range for 
a reverse search. When searching a range, SEARCH matches only text 
inside the range. It does not look at text outside the range. 

If you specify a buffer for the fourth parameter, the search starts at the 
beginning of the buffer for a forward search, or the end of the buffer for a 
reverse search. 

To determine whether the searched text contains a match, SEARCH 
examines the character at the starting position and attempts to match the 
character against the pattern, text, or keyword specified. By default, the 
search is unanchored. This allows SEARCH to move one character in the 
direction of the search if the character at the start position does not match. 
SEARCH continues in this manner until it finds a match or reaches the 
bounds of the buffer or range. 

To prevent SEARCH from moving the starting position in the direction of 
the search, use the ANCHOR keyword when you define the pattern to be 
matched. 

SEARCH does not change the current buffer or the editing point in that 
buffer. 

For more information about searching, see Chapter 2. 


SIGNALED 

ERRORS 

TPU$_STRNOTFOUND 

WARNING 

Search for a string or pattern was 
unsuccessful. 


TPU$_TOOFEW 

ERROR 

SEARCH requires at least two 
arguments. 


TPU$_TOOMANY 

ERROR 

SEARCH accepts no more than 
four arguments. 


TPU$_ARGMISMATCH 

ERROR 

One of the parameters to 
SEARCH is of the wrong type. 


TPU$JNVPARAM 

ERROR 

One of the parameters to 
SEARCH is of the wrong type. 
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TPU$_BADKEY 

WARNING 

You specified an incorrect keyword 
to SEARCH. 

TPU$_MINVALUE 

WARNING 

The integer parameter to SEARCH 
must be greater than or equal to 
- 1 . 

TPU$_MAXVALUE 

WARNING 

The integer parameter to SEARCH 
must be less than or equal to 3. 

TPU$_NOCURRENTBUF 

ERROR 

If you do not specify a buffer or 
range to search, you must position 
to a buffer before searching. 

TPU$_CONTROLC 

ERROR 

You pressed CTRL/C while 
SEARCH was executing. 

TPU$JLLPATAS 

ERROR 

The pattern to SEARCH contained 
a partial pattern assignment to a 
variable not defined in the current 
context. 


EXAMPLES 

D user_range := SEARCH ("Reflections of MONET", FORWARD, NO_EXACT) 

If you search a buffer in which the string "Reflections of Monet" appears, 
this assignment statement stores the characters "Reflections of Monet" in 
the range iiser_range. The search finds a successful match even though 
the characters in the word "Monet" do not match in case, because you 
specified NO_EXACT. 

g PROCEDURE user_find_chap 
LOCAL chap, 

found_range; 

ON__ERROR 

IF ERROR = TPU$__STRNOTFOUND 
THEN 

MESSAGE ("CHAPTER not found."); 

ELSE 

MESSAGE (MESSAGE__TEXT (ERROR) ) ; 

ENDIF; 

ENDON__ERROR; 

chap := LINE_BEGIN + "CHAPTER"; 

found__range := SEARCH (chap, FORWARD, NO_EXACT); 

IF found_range <> 0 ! No match found. 

THEN 

POSITION (founderange); 

ENDIF; 

ENDPROCEDURE; 


This procedure searches for the word “CHAPTER” appearing at the 
beginning of a line. If SEARCH finds the word, the built-in positions 
to the beginning of the string. If SEARCH does not find the word, the 
built-in writes an appropriate message in the message buffer. 
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PROCEDURE user_search_range 
LOCAL found__count; 

ON_ERROR 

[ TPU$__STRNOTFOUND, TPU$_CONTROLC ] : 

MESSAGE ( FAO ("Found !SL occurrences.", found_count)); 
RETURN; 

[OTHERWISE]:ABORT; 

ENDON_ERROR; 

found_count := 0; 
the_pattern := "blue skies"; 

the_range := CREATE_RANGE (BEGINNING_OF (CURRENT_BUFFER), 

END_OF (CURRENT_BUFFER), 

NONE); 

found_range := CREATE_RANGE (BEGINNING_OF (CURRENT_BUFFER), 

BEGINNING_OF (CURRENT_BUFFER), 
NONE); 

LOOP 

the_range := CREATE_RANGE (END_OF (found_range), 

END_OF (the_range), NONE); 

found__range := SEARCH (the_pattern, FORWARD, NO_EXACT, 

the_range); 

found_count := found_count + 1; 

ENDLOOP; 

ENDPROCEDURE; 


This procedure searches the range the_range for all occurrences of 
the pattern “blue skies”. If SEARCH finds the pattern, the procedure 
redefines the_range to begin after the end of the pattern just found. If 
the procedure did not redefine the range, SEARCH would keep finding 
the first occurrence over and over. The procedure reports the number of 
occurrences of the pattern. 
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SEARCH QUIETLY 


Looks for a particular arrangement of characters in a buffer or range and 
returns a range that contains those characters. Unlike the SEARCH built-in, 
SEARCH_QUIETLY does not signal TPU$_STRNOTFOUND when it fails to 
find a string. 


FORMAT 


I range2 := ] SEARCH_QUIETLY 


ANCHOR 

BUFFER_BEGIN 

BUFFER_END 

LINE_BEGIN 

LINE_END 

PAGE_BREAK 

pattern 

REMAIN 


{ FORWARD \ f 
I REVERSE / 


EXACT 

NO_EXACT 

integer 


string 

UNANCHOR 



PARAMETERS ANCHOR 

A keyword directing SEARCH_QUIETLY to start a search at the current 
character position. 

BUFFER_BEGIN 

A keyword used to match the beginning of a buffer. 

BUFFER_END 

A keyword used to match the end of a buffer. 

UNE_BEGIN 

A keyword used to match the be ginning of a line. 

UNE_END 

A keyword used to match the end of a line. 

PAGE_BREAK 

A ke 3 rword used to match a form-feed character. 

pattern 

The pattern that you want to match. 

REMAIN 

A keyword specifying a match starting at the current character and 
continuing to the end of the current line. 

String 

The string that you want to match. 
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UNANCHOR 

A ke)rword specifying that the nejct pattern element can match anywhere 
after the previous pattern element. Use this keyword as part of a complex 
pattern. 

For more information on these keywords, refer to the individual 
descriptions of them in this chapter. 

FORWARD 

Indicates a search in the forward direction. 

REVERSE 

Indicates a search in the reverse direction. 

EXACT 

Indicates that the characters SEARCH_QUIETLY is trying to match must 
be the seime case and have the same diacritical markings as those in the 
string or pattern used as the first parameter to SEARCH_QUIETLY. 

NO_EXACT 

Indicates that the characters SEARCH_QUIETLY is trying to match need 
not be the same case nor have the same diacritical markings as those in 
the string or pattern used as the first parameter to SEARCH_QUIETLY. 
NO_EXACT is the default value for the optional third parameter. 

integer 

Specifies how SEARCH_QUIETLY should handle case and diacritical 
information if you want to match one attribute and ignore the other. 
Digital recommends that you use the defined constants available for 
specifying this integer. The defined constants are as follows: 

• TPU$K_SEARCH_CASE — Equivalent to the integer 1. This specifies 
that the search should match the case of the first parameter but be 
insensitive to the diacritical markings of the first parameter. 

• TPU$K_SEARCH_DIACRITICAL — Equivalent to the integer 2. This 
specifies that the search should match the diacritical markings of the 
first parameter but be insensitive to the case of the first parameter. 

buffer 

The buffer in which to search. SEARCH_QUIETLY starts at the beginning 
of the buffer when doing a forward search and at the end of the buffer 
when doing a reverse search. 

rangel 

The range in which to search. SEARCH__QUIETLY starts at the beginning 
of the range when doing a forward search and at the end of the range 
when doing a reverse search. 

To search a range for all occurrences of a pattern, you must define the 
range d 3 niamically after each successful match. Otherwise, SEARCH_ 
QUIETLY positions to the beginning of the range and finds the same 
occurrence over and over. See the example section for a procedure that 
searches for all occurrences of a pattern in a range. 
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return value 


DESCRIPTION 


SIGNALED 

ERRORS 


The range containing characters that match the pattern or string specified 
as a parameter. 


SEARCH_QUIETLY looks for text that matches the string, pattern, or 
keyword specified as its first parameter. If it finds such text, it creates a 
range cont 2 dning this text and returns it. If SEARCH_QUIETLY does not 
find a match, the built-in returns 0. 

The starting position for the search depends on the optional fourth 
parameter and the search direction. If you do not specify the fourth 
parameter, the search starts at the editing point. 

If you specify a range for the fourth parameter, the search starts at the 
beginning of the range for a forward search, or the end of the range for 
a reverse search. When searching a range, SEARCH_QUIETLY matches 
only text inside the range. It does not look at text outside the range. 

If you specify a buffer for the fourth parameter, the search starts at the 
beginning of the buffer for a forward search, or the end of the buffer for a 
reverse search. 

To determine whether the searched text contains a match, SEAECH_ 
QUIETLY examines the character at the starting position and attempts 
to match the character against the pattern, text, or kejword specified. 

By default, the search is unanchored. This allows SEARCH_QUIETLY 
to move one character in the direction of the search if the character at 
the start position does not match. SEARCH_QUIETLY continues in this 
manner until it finds a match or reaches the bounds of the buffer or range. 

To prevent SEARCH_QUIETLY from moving the starting position in the 
direction of the search, use the ANCHOR keyword when you define the 
pattern to be matched. 

SEARCH_QUIETLY does not change the current buffer or the editing 
point in that buffer. 

For more information about searching, see Chapter 2. 


TPU$_TOOFEW 

ERROR 

SEARCH_OUIETLY requires at 
least two arguments. 

TPU$_TOOMANY 

ERROR 

SEARCH_QUIETLY accepts no 
more than four arguments. 

TPU$_ARGMISMATCH 

ERROR 

One of the parameters to 
SEARCH_QUIETLY is of the 
wrong type. 

TPU$JNVPARAM 

ERROR 

One of the parameters to 
SEARCH_QUIETLY is of the 
wrong type. 

TPU$_BADKEY 

WARNING 

You specified an incorrect keyword 
to SEARCH_QUIETLY. 
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TPU$_MINVALUE 

WARNING 

The integer parameter to 
SEARCH_QUIETLY must be 
greater than or equal to -1. 

TPU$_MAXVALUE 

WARNING 

The integer parameter to 
SEARCH_QUIETLY must be 
less than or equal to 3. 

TPU$_NOCURRENTBUF 

ERROR 

If you do not specify a buffer or 
range to search, you must position 
to a buffer before searching. 

TPU$_CONTROLC 

ERROR 

You pressed CTRUC while 
SEARCH_QUIETLY was 
executing. 

TPU$JLLPATAS 

ERROR 

The pattern to SEARCH_QUIETLY 
contained a partial pattern 
assignment to a variable not 
defined in the current context. 


EXAMPLES 

D user_range := SEARCH_QUIETLY ("Reflections of MONET", FORWARD, NONEXACT) 

If you are searching a buffer in which the string "Reflections of Monet" 
appears, this assignment statement stores the characters "Reflections of 
Monet" in the range user_range. The search finds a successful match even 
though the characters in the word "Monet" do not match in case, because 
you specified NONEXACT. 

If the string "Reflections of Monet" does not appear in the buffer, 
SEARCH_QUIETLY assigns the value 0 to the variable user_range. It 
does not signal the TPU$_STRNOTFOUND error. 

§ PROCEDURE user_find_chap 

LOCAL chap, 

found_range; 

chap := LINE__BEGIN + "CHAPTER"; 

found_range := SEARCH_QUIETLY (chap, FORWARD, NO_EXACT); 

IF found_range = 0 
THEN 

MESSAGE ("Chapter not found."); 

ELSE 

POSITION (found_range); 

ENDIF; 

ENDPROCEDURE; 


This procedure searches for the word "CHAPTER" appearing at the 
beginning of a line. If the procedure finds the word, the procedure 
positions to the beginning of the string. If the procedure does not find 
the word, the procedure writes an appropriate message in the message 
buffer. Compare this example procedure to the corresponding procedure in 
the description of SEARCH. 
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§ PROCEDURE user_search__range 
LOCAL found_count; 

ON_ERROR 

[TPU$_CONTROLC]: 

MESSAGE ( FAO ("Found !SL occurrences.", found_count)); 

RETURN; 

[OTHERWISE]: 

ABORT; 

ENDON_ERROR; 

found_count := 0; 
the_pattern := "blue skies"; 

the__range := CREATE_RANGE (BEGINNING_OF (CURRENT_BUFFER), 

END_OF (CURRENT_BUFFER), NONE); 

found_range := CREATE_RANGE (BEGINNING___OF (CURRENT_BUFFER) , 

BEGINNING_OF (CURRENT__BUFFER) , NONE) ; 

LOOP 

the_range := CREATE_RANGE (END_OF (found_range), 

END_OF (the_range), NONE); 

found__range := SEARCH_QUIETLY (the_pattern, FORWARD, 

NO_EXACT, the_range); 

found__count := found_count + 1; 

ENDLOOP; 

ENDPROCEDURE; 


This procedure searches the range thejrange for all occurrences of 
the pattern “blue skies”. If SEARCH_QUIETLY finds the pattern, the 
procedure redefines thejrange to begin after the end of the pattern just 
found. If the procedure did not redefine the range, SEARCH_QUIETLY 
would keep finding the first occurrence over and over. The procedure 
reports the number of occurrences of the pattern. Notice that a procedure 
using SEARCH.QUIETLY does not trap the TPU$_STRNOTFOUND error, 
because SEARCH_QUIETLY does not signal this error. 
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SELECT 

Returns a marker for the editing point in the current buffer. You must specify 
how the marker is to be dispiayed on the screen (no special video, reverse 
video, boided, biinking, or underiined). 

The marker returned by SELECT indicates the first character position in a 
seiect range. The video attribute that you specify for the marker appiies to all 
the characters in a seiect range. For information on creating a seiect range, 
see SELECT_RANGE. 

FORMAT 

r BLINK 

BOLD 

marker := SELECT ( < NONE 

REVERSE 

1 UNDERLINE J 

PARAMETERS 

BLINK 

Specifies that the selected characters are to blink. 

BOLD 

Specifies that the selected characters are to be bolded. 

NONE 

Applies no video attributes to selected characters. 

REVERSE 

Specifies that the selected characters are to be displayed in reverse video. 

UNDERLINE 

Specifies that the selected characters are to be underlined. 

return value 

A marker for the editing point in the current buffer. 

DESCRIPTION 

SELECT returns a specisil marker that establishes the beginning of a 
select range. The marker is positioned at the character position that is 
the editing point when the built-in procedure SELECT is executed. (The 
marker is actually positioned between character positions, rather than on 
a character position.) A select range includes all the characters between 
the select marker and the current position, but not the character at the 
current position. 

Using SELECT may cause VAXTPU to insert padding spaces or blank 
lines in the buffer. SELECT causes the screen manager to place the 
editing point at the cimsor position if the current buffer is mapped to a 
visible window. (For more information on the distinction between the 
cursor position and the editing point, see Chapter 6.) If the cursor is not 
located on a character (that is, if the cursor is before the beginning of a 
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line, beyond the end of a line, in the middle of a tab, or below the end of 
the buffer), VAXTPU inserts padding spaces or blank lines into the buffer 
to fill the space between the cursor position and the nearest text. 

Only one select marker for a buffer can be active at any one time. If a 
buffer is associated with more than one visible window, the select range is 
displayed in only one window (the current or most recent window). 

If the buffer in which you are selecting text is associated with the current 
window, as you move from the select marker to another character position 
in the same buffer, all the characters over which you move the cursor are 
included in the select range, and the video attribute that you specify for 
the select marker is applied to the characters in the range. The video 
attribute of a selected character is not visible when you are positioned on 
the character, but once you move beyond the character, the character is 
displayed with the attribute you specify. 

If two or more windows are mapped to the same buffer and one of the 
windows is the current window, only the current window displays the 
select area. If two or more windows are mapped to different buffers, it 
is possible to have more than one visible select area on the screen at the 
same time. If none of the windows on the screen is the current window, 
the visible window that was most recently current displays the select area. 

If the current character is deleted, the marker moves to the nearest 
character position. The nearest character position is determined in the 
following way: 

1 If there is a character position on the same line to the right, the 
marker moves to this position, even if the position is at the end of the 
line. 

2 If the line on which the marker is located is deleted, the marker moves 
to the first position on the following line. 

If you are positioned at the select marker and you insert text, the select 
marker moves to the first character of the inserted text. You can move 
one column past the last character in a line. (With free cursor motion, you 
can move even fiirther beyond the last character of a line.) However, if 
you establish a select marker beyond the last character in a line, no video 
attribute is visible for the marker. 


SIGNALED 

ERRORS 


TPU$_ONESELECT 


WARNING SELECT is already active in the 
current buffer. 


TPU$_TOOFEW 

TPU$_TOOMANY 


ERROR SELECT requires one argument. 

ERROR SELECT accepts only one 

argument. 

ERROR SELECT must be on the right- 


TPU$_NEEDTOASSIGN 


hand side of an assignment 
statement. 
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TPU$_NOCURRENTBUF 

TPU$_BADKEY 

TPU$JNVPARAM 


ERROR You must position to a buffer 
before using SELECT. 

WARNING You specified the wrong keyword 
to SELECT. 

ERROR SELECT’S parameter is not a 
keyword. 


EXAMPLES 

D select__mark ;= SELECT (NONE) 

This assignment statement places a marker at the editing point. Because 
NONE is specified, no video attributes are applied to a select range that 
has this marker as its beginning. 

g select_mark_under := SELECT (UNDERLINE) 

This assignment statement places a marker at the editing point. Any 
characters included in a select range that has this marker as its beginning 
are underlined. 

§ ! Bold selected text 

PROCEDURE user_start_select 

user__v__beginning_of_select := SELECT (BOLD) ; 

ENDPROCEDURE; 


This procedure creates a bold marker that is used as the beginning of a 
select region. As you move the cursor, the characters that you select are 
bolded. To turn off the selection of characters, set the variable user_v_ 
beginningjofjselect to 0. 
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SELECT_RANGE 



Returns a range that contains all the characters between the marker 
established with the built-in procedure SELECT and the editing point. 
SELECT_RANGE does not include the current character. 

FORMAT 

range := SELECT_RANGE 

PARAMETERS 

None. 

return value 

A range containing all the characters between the marker established with 
SELECT and the editing point. 

DESCRIPTION 

If you select text in a forward direction, the select range includes the 
marked character and all characters up to but not including the current 
character. If you select text in a reverse direction from the marker, the 
select range includes the current character and all characters up to but 
not including the marked character. 

SELECT_RANGE is used in conjunction with SELECT to allow the user 
to mark a section of text for treatment as an entity. 

The procedure for selecting a section of text is the following: 

1 Use the built-in procedure SELECT to place a marker at the beginning 
of the section you want to select. The following example illustrates: 

ml := SELECT (NONE); 

2 Mark the characters that you want in the select region by moving from 
character to character with the cursor. 

3 When all of the text is selected, create a range that contains the 
selected text. The following example illustrates: 

rl := SELECT_RANGE; 

4 Stop the selection of characters by setting the marker that marks the 
beginning of the range to 0. The following example illustrates: 

ml := 0; 

Using SELECT_RANGE may cause VAXTPU to insert padding spaces or 
blank lines in the buffer. SELECT_RANGE causes the screen manager 
to place the editing point at the cursor position if the current buffer is 
mapped to a visible window. (For more information on the distinction 
between the cursor position and the editing point, see Chapter 6.) If the 
cursor is not located on a character (that is, if the cursor is before the 
beginning of a line, beyond the end of a line, in the middle of a tab, or 
below the end of the buffer), VAXTPU inserts padding spaces or blank 
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lines into the buffer to fill the space between the cursor position and the 
nearest text. 


SIGNALED 

ERRORS 

TPU$_NOSELECT 

WARNING 

There is no active select range in 
the current buffer. 


TPU$_SELRANGEZERO 

WARNING 

The select range contains no 
selected characters. 


TPU$_NEEDTOASSIGN 

ERROR 

SELECT_RANGE must be on the 
right-hand side of an assignment 
statement. 


TPU$_TOOMANY 

ERROR 

SELECT_RANGE takes no 
arguments. 


TPU$_NOCURRENTBUF 

WARNING 

There is no current buffer. 


EXAMPLES 

B select^l := SELECT_RANGE 

This assignment statement puts the range for the currently selected 
characters in the variable select Jl, 

B PROCEDURE user_select 

! Start a select region 

user_select_position SELECT (REVERSE); 

MESSAGE ("Selection started."); 

! Move 5 lines and create a select region 

MOVE_VERTICAL (5); 

SRI := SELECT_RANGE; 

! Move 5 lines and create another select region 

MOVE_VERTICAL (5); 

SR2 := SELECT_RANGE; 

! Stop the selection by setting the select marker to 0. 

user__select_position := 0; 

ENDPROCEDURE; 


This procedure shows the use of SELECT_RANGE multiple times in the 
same procedure. 
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SEND 

Passes data to a subprocess. 

FORMAT 

r buffer ) 

SEND ('< range y process) 

[ string J 

PARAMETERS 

buffer 

The buffer whose contents you want to send to the subprocess. 

range 

The range whose contents you want to send to the subprocess. 

String 

The string that you want to send to the subprocess. 

process 

The process to which you want to send data. 

DESCRIPTION 

All output from the process is stored in the buffer that was associated with 
the process when you created it. See the CREATE_PROCESS built-in. 
Your editing stops until the process responds to what is sent. 

If you specify a buffer or a range as the data to pass to a process, the lines 
of the buffer or range are sent as separate records. 


SIGNALED 

ERRORS 


TPU$_NOPROCESS 

WARNING 

Subprocess that you tried to send 
to has already terminated. 

TPU$_SENDFAIL 

WARNING 

Unable to send input to a 
subprocess. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
SEND built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the SEND built-in. 

TPU$JNVPARAM 

ERROR 

Wrong type of data sent to the 
SEND built-in. 

TPU$_NOTMODIFIABLE 

WARNING 

Attempt to change unmodifiable 
buffer. The buffer to which a 
subprocess writes output must be 
modifiable. 
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TPU$_DELETEFAIL 


WARNING Unable to terminate the 
subprocess. 

WARNING Input buffer is the same as the 
output buffer. 

ERROR The execution of the command 


TPU$_NOSENDBUF 


TPU$_CONTROLC 


you sent terminated because you 
pressed CTRL/C. 


EXAMPLES 

Q SEND ("directory", user_process) 


This statement sends the DCL command DIRECTORY to the process 
named user j)rocess. The process must already be created with the built-in 
procedure CREATE_PROCESS so that the output can be stored in the 
buffer associated with the process. 


g PROCEDURE mail__subp 

! Create a buffer and a window that a subprocess can run in 

v_mail_buffer := CREATE___BUFFER ("main_buffer"); 
v_mail_window := CREATE_WINDOW (1, 22 , ON); 

! Map the mail window to the screen 

UNMAP (MAIN__WINDOW) ; 

MAP (v_mail_window, v__mail_buf fer) ; 

! Create a subprocess and send "mail" as the first command 

pi ;= CREATE_PROCESS (v_mail__buffer, "MAIL") ; 

! Position to the subprocess and use read__line for next command 

POSITION (v_mail_window); 

si := READ__LINE ("mail__subp> ", 20); 

SEND (si, pi); 

ENDPROCEDURE; 


This procedure uses the built-in procedure SEND to pass a command to a 
process in which the Mail Utility is running. The command to be sent to 
the process is obtained with the built-in procedure READ_LINE. 
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SEND CLIENT MESSAGE 



Sends either of two client messages—STUFF_SELECTION or KILL_ 
SELECTION—^to other DECwindows applications. 

FORMAT 

SEND.CLIENT.MESSAGE f { ~ 

PARAMETERS 

KILL_SELECTION 

A ke 3 rword indicating that the client message to be sent is the KILL_ 
SELECTION client message. 

SEND_CLIENT_MESSAGE (KILL_SELECTION) is used when the user 
wants to copy something from another application that owns the input 
focus to the VAXTPU/EVE-layered application without input focus. It also 
removes the text from that other application. 

The user selects the text in the application that owns the input focus. The 
user positions the pointer cursor to the desired location in the VAXTPU 
/EVE-layered application and then presses the CTRL key and clicks on 
the MBS mouse button. In this circumstance, the VAXTPU/EVE-layered 
application inserts the selected text emd uses SEND_CLIENT_MESSAGE 
(KILL_SELECTION) to send a message directing the application that 
owns the input focus to delete the selected text. 

STUFF_SELECTION 

A kejnvord indicating that the client message to be sent is the STUFF_ 
SELECTION client message. 

SEND_CLIENT_MESSAGE (STUFF.SELECTION) is used when the user 
wants to copy something from an apphcation layered on VAXTPU or EVE 
into some DECwindows application that owns the input focus. 

To select the text to be copied, the user does an MB3DRAG operation 
in the VAXTPU/EVE-layered application. The VAXTPU/EVE-layered 
application grabs ownership of the secondary global selection. The selected 
text is the secondary global selection. 

The VAXTPU/EVE-layered application then uses SEND CLIENT 
MESSAGE (STUFF.SELECTION) to send a STUFF.SELECTION client 
message to the application that owns the input focus. In response, the 
application requests to read the secondary global selection. This causes 
the VAXTPU/EVE-layered apphcation to write to the secondary global 
selection, which is then received by the other apphcation. 

Note that if the user uses CTRL/MB3DRAG instead of MB3DRAG, the last 
step is that the text in the secondary global selection is deleted from the 
VAXTPU/EVE-based apphcation. 

DESCRIPTION 

Note that the VAXTPU/EVE-layered apphcation cannot designate the 
apphcation that is to receive the client message. VAXTPU handles sending 
the message to the correct DECwindows apphcation. 
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SIGNALED 




ERRORS 

TPU$_NORETURNVALUE 

ERROR 

Does not return a value. 

TPU$_TOOFEW 

ERROR 

SEND_CLIENT_MESSAGE 
requires one argument. 


TPU$_TOOMANY 

ERROR 

SEND_CLIENT_MESSAGE 
accepts only one argument. 


TPU$_BADKEY 

WARNING 

Keyword must be either KILL 
SELECTION or STUFF 
SELECTION. 


TPU$JNVPARAM 

ERROR 

The parameter must be a keyword. 


TPU$_NOGBLSELDATA 

WARNING 

There is no owner of the 
PRIMARY global selection to 
send a client message to. 


TPU$_NOFOCUSOWNER 

WARNING 

There is no owner of the input 
focus to send a client message to. 
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SEND_EOF 

Uses features of the VMS mailbox driver to send an end-of-file message 
(IO$_WRITEOF) to a process. 

FORMAT 

SEND_EOF (process) 

PARAMETERS 

process 

The process to which the end-of-file message is being sent. 

DESCRIPTION 

The end-of-file message causes a pending read from a subprocess to be 
completed with an SS$_ENDOFFILE status. See the VMS I/O User's 
Reference Volume for more information on the Write End-of-File message. 


SIGNALED 

ERRORS 


TPU$_SENDFAIL 

WARNING 

Unable to send input to a 
subprocess. 

TPU$_NOPROCESS 

WARNING 

No subprocess to send to. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
SEND_EOF built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the SEND__EOF built-in. 

TPU$JNVPARAM 

ERROR 

Wrong type of data sent to the 
SEND^EOF built-in. 

TPU$_NOTMODIFIABLE 

WARNING 

Attempt to change unmodifiable 
buffer. The buffer to which a 
subprocess writes output must be 
modifiable. 

TPU$_DELETEFAIL 

WARNING 

Unable to terminate the 
subprocess. 


EXAMPLE 

SEND__EOF (sub__procl) 


This statement sends an end-of-file to sub j)rocl. 
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SET 

Lets you establish or change certain features of a VAXTPU session. SET 
requires a keyword as its first parameter. The keyword indicates which feature 
of the editor is being set. You can set the mode for entering text, the text that 
is to be displayed on certain parts of the screen, the direction of a buffer, the 
status of a buffer, and so on. 

FORMAT 

SET (keyword, parameter [,.. J) 

PARAMETERS 

keyword 

The ke3nvord used as the first parameter specifies which feature is being 
established or changed. Following are the valid ke)nvords for SET: 

ACTIVE AEEA 

AUTO REPEAT 

BELL 

CLIENT MESSAGE 

COLUMN MOVE VERTICAL 

CROSS WINDOW BOUNDS 

DEBUG 

DEFAULT DIRECTORY 

DETACHED ACTION 

DISPLAY VALUE 

DRM HIERARCHY 

ENABLE RESIZE 

EOB TEXT 

ERASE UNMODIFIABLE 

FACILITY NAME 

FORWARD 

GLOBAL SELECT 

GLOBAL SELECT GRAB 

GLOBAL SELECT READ 

GLOBAL SELECT TIME 

GLOBAL SELECT UNGRAB 

HEIGHT 

ICON NAME 

ICON PIXMAP 

ICONIFY PDOVIAP 

INFORMATIONAL 

INPUT FOCUS 

INPUT FOCUS GRAB 

INPUT FOCUS UNGRAB 

INSERT 

JOURNALING 

KEY MAP LIST 

KEYSTROKE RECOVERY 

LEFT MARGIN 

LEFT MARGIN ACTION 

LINE NUMBER 

MAPPED WHEN MANAGED 

MARGINS 
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MAX_LINES 

MENU.POSITION 

MESSAGE_ACTION_LEVEL 

MESSAGE_ACTION_TYPE 

MESSAGE.FLAGS 

MODIFIABLE 

MODIFIED 

MOUSE 

NO_WRITE 

OUTPUT_FILE 

OVERSTRIKE 

PAD 

PAD_OVERSTRUCK_TABS 

PERMANENT 

POST_KEY_PROCEDURE 

PRE_KEY_PROCEDURE 

PROMPT_AREA 

RECORD_ATTRIBUTE 

RESIZE_ACTION 

REVERSE 

RIGHT.MARGIN 

RIGHT_MARGIN_ACTION 

SCREEN_LIMITS 

SCREEN_UPDATE 

SCROLL_BAR 

SCROLL_BAR_AUTO_THUMB 

SCROLLING 

SELFJNSERT 

SHIFT_KEY 

SPECIAL_ERROR_SYMBOL 

STATUS_LINE 

SUCCESS 

SYSTEM 

TAB_STOPS 

TEXT 

TIMER 

TRACEBACK 

UNDEFINED_KEY 

VIDEO 

WIDGET 

WIDGET_CALL_DATA 

WIDGET_CALLBACK 

WIDTH 


These keywords and the parameters that follow them are described on 
the following pages. The descriptions of the ke3Words are organized 
alphabetically. 

parameter ... ] 

The number of parameters following the first parameter varies according 
to the keyword you use. The parameters are listed in the format section of 
the applicable keyword description. 
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DESCRIPTION 


The built-in procedure SET can be used by both the programmer creating 
an editing interface and the person using the interface. The programmer 
can establish certain default behavior and screen displays for an editing 
interface. The user can change the default behavior and do some simple 
customizing of an existing VAXTPU interface with the built-in procedure 
SET. 
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SET (ACTIVE_AREA) 



Designates the specified area as the active area in a VAXTPU window. An 
active area is an area within which VAXTPU ignores movements of the pointer 
cursor. 

FORMAT 

SET (ACTIVE_AREA, window, column, row [, width, height ]) 

PARAMETERS 

ACTIVE_AREA 

A ke 5 word directing VAXTPU to set an attribute of the active area. 

window 

The window in which you want to define the active region. 

column 

An integer specifying the leftmost column of the active region. 

row 

An integer specifying the topmost row of the active region. If you use 0, 
the active row is the status line. 

width 

An integer specifying the width in columns of the active region. Defaults 
to 1. 

height 

An integer specifying the height in rows of the active region. Defaults 
to 1. 

DESCRIPTION 

The active area is the region in a window in which VAXTPU ignores 
movements of the pointer cursor for purposes of distinguishing clicks 
from drags. When you press down a mouse button, VAXTPU interprets 
the event as a click if the upstroke occurs in the active area with the 
downstroke. If the upstroke occurs outside the active area, VAXTPU 
interprets the event as a drag operation. 

A VAXTPU layered application can have only one active area at a time, 
even if the application has more than one window visible on the screen. 
An active area is only valid if you are pressing a mouse button. The 
default active area occupies one character cell. By default, the active area 
is located on the character cell pointed to by the pointer cursor. 

For information on mouse button clicks, see the XUI Style Guide. 

Table 7-9 lists the keywords for referring to click and drag operations. 
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Table 7-9 VAXTPU Keywords Representing Mouse Events 


M1UP 
M1DOWN 
M1DRAG 
M1 CLICK 
M1CLICK2 
M1 CLICKS 
M1CLICK4 
M1 CLICKS 


M2UP 

M2DOWN 

M2DRAG 

M2CLICK 

M2CLICK2 

M2CLICK3 

M2CLICK4 

M2CLICK5 


M3UP 

M3DOWN 

M3DRAG 

M3CLICK 

M3CLICK2 

M3CLICK3 

M3CLICK4 

M3CLICK5 


M4UP 

M4DOWN 

M4DRAG 

M4CLICK 

M4CLICK2 

M4CLICK3 

M4CLICK4 

M4CLICK5 


M5UP 

M5DOWN 

M5DRAG 

M5CLICK 

M5CLICK2 

M5CLICK3 

M5CLICK4 

M5CLICK5 


SIGNALED 

ERRORS 


TPU$_BADVALUE 

ERROR 

An integer parameter was 
specified with a value outside 
the valid range. 

TPU$_EXTRANEOUSARGS 

ERROR 

One or more extraneous 
arguments has been specified 
for a DECwindows built-in. 

TPU$JNVPARAM 

ERROR 

One of the parameters was 
specified with data of the wrong 
type. 

TPU$_NORETURNVALUE 

ERROR 

SET (ACTIVE_AREA) cannot 
return a value. 

TPU$_REQUIRESDECW 

ERROR 

You can use the SET (ACTIVE_ 
AREA) built-in only if you are using 
DECwindows VAXTPU. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
SET (ACTIVE_AREA) built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the SET (ACTIVE.AREA) built-in. 


EXAMPLE 

PROCEDURE eve$$mldown 

LOCAL the_window, 
the_column, 
the_row, 
the_width; 

ON_ERROR 

[OTHERWISE]: 

ENDON__ERROR; 

eve$$x_pre_mbl_mark := MARK (FREE_CURSOR); 
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IF LOCATE^MOUSE (the_window, the^column^ the_row) 

THEN 

eve$x__mbl__in__progress := 1; 

IF the^row = 0 
THEN 

IF eve$current_indicator (the_window, 

the_column, 
the_width) <> 0 

THEN 

IF eve$x_decwindows__active 
THEN 

SET (ACTIVE__AREA, ! This statement sets 

the_window, the_column, ! the active area. 

0, the_width, 1); 

ENDIF; 

ELSE 

RETURN (FALSE); 

ENDIF; 

ELSE 

IF the_window = eve$choice_window 
THEN 

IF eve$$current_choice (the_column, eve$$x_chosen_range) 
THEN 

IF eve$x_decwindows_active 
THEN 

SET (ACTIVE__AREA, the_window, the__column, the_row, 
eve$$x_choices_column_width, 1) ; 

ENDIF; 

ENDIF; 

else 

POSITION (MOUSE); 

eve$$x_inbl_down_free := MARK (FREE_CURSOR) ; 

POSITION (TEXT); 

eve$clear_select__j)osition; 

eve$clear_message; 

eve$$x_mbl_down__bound := MARK (NONE); 

POSITION (eve$$x_mbl_down_free); 

ENDIF; 

ENDIF; 

RETURN (TRUE); 

ELSE 

RETURN (FALSE); 

ENDIF; 

ENDPROCEDURE; 


This procedure shows one possible way that an application can use 
SET (AC'nVE_AREA). The procedure is a modified version of the 
EVE procedure EVE$$M1D0WN. You can find the original version in 
SYS$EXAMPLES:EVE$MOUSE.TPU. 

Procedure EVE$$M1D0WN, when bound to MIDOWN, sets an active area 
when you press MBl. 
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SET (AUTO_REPEAT) 


FORMAT 

SET (AUTO_REPEAT, { }; 

PARAMETERS 

AUTO_REPEAT 

A keyword indicating that SET is to control whether VAXTPU repeats 
keystrokes as long as you hold down a key. 

By default, AUTO_REPEAT is set ON. 

ON 

Specifies that a key press should continue to generate characters until the 
key is released. 

OFF 

Requires a separate keystroke for each character generated. 

DESCRIPTION 

VAXTPU sends an escape sequence to the terminal to set AUTO_REPEAT 
on or off. 

The autorepeat feature affects all keyboard keys on the VTIOO series of 
terminals except the following: 

• The SET-UP key 

• The ESC key 

• The NO SCROLL key 

• The TAB key 

• The RETURN key 

• The CTRL key and another key 

The autorepeat feature affects all keyboard keys on the VT300 series and 
VT200 series of terminals except the following: 

• The keys FI, F2, F3, F4, F5 

• The RETURN key 

If you want to slow down the movement of the cursor, you can use SET 
(AUTO_REPEAT) within a procedure that causes cursor motion. Because 
of the time the terminal requires to process the escape sequence that 
VAXTPU sends, if you turn autorepeat off before moving the cursor and 
on after the movement, you slow down the cursor movement. You may 
find it useful to slow the cursor motion at the top or bottom of a window. 
The sample procedure in the Example section shows how to do this. See 
Example 2. 

SET (AUTO_REPEAT) has no effect if you use it in DECwindows 
VAXTPU. 
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SIGNALED 



SET (AUTO_REPEAT) requires 
two parameters. 

ERRORS 

TPU$_TOOFEW 

ERROR 


TPU$_TOOMANY 

ERROR 

You specified more than two 
parameters. 


TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 


TPU$_BADKEY 

ERROR 

The keyword must be either ON ( 
OFF. 


TPU$_UNKKEYWORD 

ERROR 

You specified an unknown 
keyword. 


EXAMPLES 

Q SET (AUTO_REPEAT, OFF) 

This statement turns autorepeat off. 

§ ! Two procedures that slow the scrolling action 

PROCEDURE user_slow_up_arrow 
SET (AUTO_REPEAT, OFF); 

MOVE_VERTICAL (-1); 

SET (AUTO_REPEAT, ON); 

ENDPROCEDURE; 

PROCEDURE user_slow_down_arrow 
SET (AUTO_REPEAT, OFF); 

MOVE_VERTICAL (1); 

SET (AUTO_REPEAT, ON); 

ENDPROCEDURE; 


These procedures show how to turn AUTO_REPEAT off and on to slow the 
cursor movement. 
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SET (BELL) 


FORMAT 

SET (BELL, { jtL.nnAOT 1’ ( See ]) 

' 1 BROADCAST J 1 OFF r 

PARAMETERS 

BELL 

The terminal bell. 

ALL 

Indicates that the second parameter (ON or OFF) applies to aU messages. 

BROADCAST 

Indicates that the second parameter applies to broadcast messages only. 

ON 

Causes the terminal bell to ring when a message is written to the message 
window. 

OFF 

Turns off the audible signal of the terminal bell. 

DESCRIPTION 

When the bell is on, the terminal bell rings to signal the fact that 
a message is being written to the message window. When you use 

ALL, internal VAXTPU messages as well as broadcast messages cause 
the terminal bell to ring. To cause VAXTPU messages of success and 
informational severity level to be written to the message buffer, you must 
have used the built-in procedure SET ({INFORMATIONAL 1 SUCCESS}, 
ON). When you use BROADCAST, only broadcast messages such as mail 
notifications and REPLY messages cause the bell to ring. 

SET (BELL, ALL, (ON 1 OFF}) affects the setting of SET (BELL, 
BROADCAST, (ON 1 OFF}). If you want the behavior of broadcast 
messages to be different from other messages, use the built-in procedure 
SET (BELL, BROADCAST, (ON 1 OFF}) after using SET (BELL, ALL, 

(ON 1 OFF}). 

Note that VAXTPU causes the bell to ring as a signal that a message is 
being written to the message window, not as an interpretation of a bell 
character in the message text. Bell cheiracters in the message text are not 
interpreted, they are displayed. Positioning to the message window and 
moving the cursor to a bell character in the message text do not cause the 
terminal bell to ring. 

You can also use DCL commands to affect the display of broadcast 
messages within VAXTPU. If you use the command SET TERMINAL 
/NOBROADCAST at the DCL level, no broadcast messages are sent to 
your terminal. The DCL command SET BROADCAST eillows you to 
enable or disable certain classifications of broadcast messages. 

The bell is off by default. 
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SIGNALED 

ERRORS 

TPU$_TOOFEW 

ERROR 

SET (BELL) requires three 
parameters. 


TPU$_TOOMANY 

ERROR 

You specified more than three 
parameters. 


TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 


TPU$_BADKEY 

ERROR 

You specified an invalid keyword. 


EXAMPLES 

D SET (BELL, BROADCAST, ON) 

This statement causes the terminal bell to ring when a broadcast message 
is written to the message window. 

S PROCEDURE user__ring__bell (msg_string) 

SET (BELL, ALL, ON); ! Turn bell on 

MESSAGE (msg_string); ! Write message text to message buffer 

SET (BELL, ALL, OFF); ! Turn bell off 

SET (BELL, BROADCAST,ON); ! Turn bell on for broadcast messages 
ENDPROCEDURE; 


This procedure uses SET (BELL, ALL, ON) to cause the bell to ring for the 
message that is being sent in the second statement. After the message is 
written, the bell is turned off. SET (BELL, BROADCAST, ON) is used to 
cause broadcast messages to ring the terminal bell. 
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SET (CLIENT.MESSAGE) 



Designates the action routine to be executed when DECwindows VAXTPU 
receives a ciient message from another DECwindows application. 

FORMAT 

' buffer 

learn sequence 

SET (CLIENT_MESSAGE,SCREEN, ] program J; 

range 
. string 

PARAMETERS 

CUENT_MESSAGE 

A keyword indicating that SET is being used to designate a client message 
action routine. 

SCREEN 

A keyword used to preserve compatibility with future versions of VAXTPU. 

buffer 

The buffer containing the code to be executed when VAXTPU receives a 
client message. 

Iearn_sequence 

The learn sequence to be executed when VAXTPU receives a client 
message. 

program 

The program to be executed when VAXTPU receives a client message. 

range 

The range containing the code to be executed when VAXTPU receives a 
client message. 

String 

The string containing the code to be executed when VAXTPU receives a 
client message. 

DESCRIPTION 

A client message is a communication from one DECwindows application 
to another. The message enables the sending application to generate an 
event on the queue of the receiving application. 

SIGNALED 

ERRORS 

TPU$_COMPILEFAIL WARNING Compilation failed. 

TPU$_TOOFEW ERROR You specified too few parameters. 
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TPU$_TOOMANY 

ERROR 

You specified too many 
parameters. 

TPU$_BADKEY 

ERROR 

You specified an invalid keyword. 

TPU$_ARGMISMATCH 

ERROR 

Argument has the wrong type. 
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SET (COLUMN_MOVE_VERTICAL) 


FORMAT 

SET (COLUMN_MOVE_VERTICAL, { }; 

PARAMETERS 

COLUMN_MOVE_ VERTICAL 

Specifies that you want to use SET to control how the MOVE_VERTICAL 
built-in moves the cursor. 

ON 

Directs the MOVE_VERTICAL built-in to place the cursor in the same 
column on each new line unless doing so would put the cursor in the 
middle of a tab. If the cursor would be placed in a tab, MOVE_VERTICAL 
places the cursor at the beginning of the tab. 

OFF 

Directs the MOVE_VERTICAL built-in to place the cursor at the same 
offset in each new record to which the cursor moves. This behavior is the 
default for SET (COLUMN_MOVE_VERTICAL). Since VAXTPU counts 
a tab as one character when determining the offset, the cursor’s column 
location can change dramatically after you use MOVE_VERTICAL. 

DESCRIPTION 

When SET (COLUMN_MOVE_VERTICAL) is set to ON, you can get 
a different result from using MOVE VERTICAL (n) than from using 
MOVE_VERTICAL (1) n times. When you use MOVE_VERTICAL (3), for 
exsimple, the built-in tries to keep the cursor in the column the cursor 
occupied just before execution of MOVE_VERTICAL (3). When you use 
MOVE_VERTICAL (1) three times, the built-in resets the column where 
VAXTPU is trying to keep the cursor. Thus, if the first MOVE_VERTICAL 
(1) moves the cursor leftward to the beginning of a tab, the second MOVE_ 
VERTICAL (1) does not move the cursor rightward again. 

When SET (COLUMN_MOVE_VERTICAL) is set to OFF, MOVE. 
VERTICAL (n) produces the same results as MOVE.VERTICAL (1) n 
times. 

To determine whether COLUMN_MOVE_VERTICAL is set to ON or OFF, 
use the following statement: 

boolean := GET_INFO (SYSTEM, "COLUMN_MOVE_VERTICAL") 

This GET.INFO call returns 1 if COLUMN_MOVE_VERTICAL is set to 
ON, 0 if it is set to OFF. 

If you have previously written extensions to EVE and want to layer the 
extensions on EVE, you may have to rewrite some procedures because EVE 
sets COLUMN_MOVE_VERTICAL to ON. For instance, if your extension 
contains the following code and if the first line has a left margin further to 
the right than the second line, the code may not work as intended: 

MOVE HORIZONTAL (-CURRENT OFFSET); ! Go to beginning of line 

MOVE VERTICAL (1); ! Move down a line 
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SIGNALED 

ERRORS 


EXAMPLES 


To compensate for the fact that EVE sets COLUMN_MOVE_VER'nCAL to 
ON, you can substitute the following code for the code shown above: 

POSITION (LINE_END); ! Go to end of existing line 

MOVE HORIZONTAL (1); ! Advance to start of next line 


TPU$_TOOFEW 

ERROR 

SET (COLUMN_MOVE_ 
VERTICAL) requires two 
parameters. 

TPU$_TOOMANY 

ERROR 

You specified more than two 
parameters. 

TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 

TPU$_BADKEY 

ERROR 

The keyword must be either ON or 
OFF. 


In the following example, the S 5 nnbol ”>" represents a tab character. The 
underscore shows the cursor location. 

Suppose you have the following two lines of text in a buffer, with the 
cursor on the "c" in the first line: 

abodefg 

a>.bcdefg 

If you use the following code, the cursor ends up pointing to the “b” on the 
second line: 

SET (COLUMN__MOVE_VERTICAL, OFF) ; 

MOVE_VERTICAL (1); 

After the MOVE_VERTICAL (1) statement, the cursor location is as 
follows: 

abcdefg 

a>.bcdefg 

On the other hand, suppose you have the same text, as follows: 

abcdefg 

a>.bcdefg 

If you use the following code, the cursor ends up pointing to the beginning 
of the tab on the second line: 

SET (COLUMN_MOVE_VERTICAL, ON); 

MOVE_VERTICAL (1); 

After the MOVE_VERTICAL (1) statement, the cursor location is as 
follows: 

abcdefg 

a>.bcdefg 
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SET (CROSS_WINDOW_BOUNDS) 


FORMAT 

SET (CROSS_WINDOW_BOUNDS. { 

PARAMETERS 

CROSS_ WINDOW_BOUNDS 

A keyword specifying that SET is to control the way the CURSOR_ 
VERTICAL built-in procedure behaves at a window boundary. 

The default setting for CROSS_WINDOW_BOUNDS is ON (preserving the 
behavior from previous versions of VAXTPU). 

ON 

Causes the CURSOR_VERTICAL built-in procedure to cross window 
boundaries and to ignore scrolling regions. However, even when crossing 
of window bounds is enabled, the CURSOR_VERTICAL built-in procedure 
still obeys screen boundaries. That is, if CURSOR_VERTICAL brings the 
cursor to the edge of the screen, VAXTPU scrolls text into the window 
rather than making the cursor invisible. 

OFF 

Prevents the CURSOR_VERTICAL built-in procedure from crossing 
window boundaries and causes CURSOR_VERTICAL to obey scrolling 
regions. 

SIGNALED 

ERRORS 

TPU$_TOOFEW ERROR SET (CROSS_WINDOW_ 

BOUNDS) requires two 
parameters. 

TPU$_TOOMANY ERROR You specified more than two 

parameters. 

TPU$JNVPARAM ERROR One or more of the specified 

parameters have the wrong type. 

TPU$_BADKEY ERROR You specified an invalid keyword. 


EXAMPLE 

SET (CROSS_WINDOW_BOUNDS, OFF) 

This statement prevents subsequent invocations of the CURSOR_ 
VERTICAL built-in procedure from crossing window boundaries and 
causes the screen to scroll if the cursor moves into a scrolling region. This 
is the setting that the EVE editor now uses. 
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SET (DEBUG) 



Controls various attributes of a debugging program that helps locate VAXTPU 
programming errors. 

Note that this built-in has five valid syntax permutations. You cannot use any 
combinations of parameters not shown in this description. 

FORMAT 

' buffer 

SET (DEBUG, PROGRAM, { 1) 

' range ' 

. sffmgf 

PARAMETERS 

DEBUG 

A keyword indicating that SET is to control various attributes of a 
debugging program that helps locate VAXTPU programming errors. 

PROGRAM 

A keyword indicating that VAXTPU is to use a user-written debugger. 

buffer 

An expression evaluating to a buffer that contains a procedure or program. 

The statement SET (DEBUG, PROGRAM, buffer) directs VAXTPU to use 
the user-written debugger contained in the specified buffer during the 
current debugging session. 

program 

A variable of type program. 

The statement SET (DEBUG, PROGRAM, program) directs VAXTPU to 
use the user-written debugger contained in the specified program during 
the current debugging session. 

range 

An expression evaluating to a range that contains a procedure or program. 

The statement SET (DEBUG, PROGRAM, range) directs VAXTPU to use 
the user-written debugger contained in the specified range during the 
current debugging session. 

String 1 

A string containing executable VAXTPU statements. 

The statement SET (DEBUG, PROGRAM, string 1) directs VAXTPU to 
use the VAXTPU statements in the specified string during the current 
debugging session. 
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FORMAT 

SET (DEBUG. { 

PARAMETERS 

DEBUG 

A ke 3 rword indicating that SET is to control various attributes of a 
debugging program that helps locate VAXTPU programming errors. 

ON 

A keyword that enables single-stepping. 

The statement SET (DEBUG, ON) directs VAXTPU to execute just one 
line of code and then return control to the debugger. 

OFF 

A ke 3 nvord that disables single-stepping. 

The statement SET (DEBUG, OFF) disables single-step execution. Since 
single-stepping is off by default, this format is usehil only to turn off 
single-stepping after single-stepping has been turned on. 

FORMAT 

SET (DEBUG, { }, string2) 

PARAMETERS 

DEBUG 

A keyword indicating that SET is to control various attributes of a 
debugging program that helps locate VAXTPU programming errors. 

ON 

A keyword that sets a breakpoint. 

The statement SET (DEBUG, ON, string2) directs VAXTPU to set a 
breakpoint at the procedure named by string2. 

OFF 

A keyword that cancels one or more breakpoints. 

The statement SET (DEBUG, OFF, string2) cancels a breakpoint 
previously set at the procedure named by string2. 

strmg2 

The name of a procedure. 

The format SET (DEBUG, ON, string2) or SET (DEBUG, OFF, string2) 
sets or cancels a breakpoint at the procedure specified by string2. 
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FORMAT 

SET (DEBUG, OFF. ALL) 

PARAMETERS 

DEBUG 

A ke 3 rword indicating that SET is to control various attributes of a 
debugging program that helps locate VAXTPU programming errors. 

OFF 

A keyword that cancels breakpoints. 

The statement SET (DEBUG, OFF, ALL) cancels all breakpoints set during 
the debugging session. 

ALL 

A keyword indicating that all breakpoints are to be canceled. 

The statement SET (DEBUG, OFF, ALL) clears all breakpoints. 

FORMAT 

SET (DEBUG, Strings, value) 

PARAMETERS 

DEBUG 

A ke 3 nvord indicating that SET is to control various attributes of a 
debugging program that helps locate VAXTPU programming errors. 

Strings 

The name of a global variable, local variable, or parameter. When you 
use Strings to specify a local variable or a parameter, the variable or 
parameter must be in the procedure you are currently debugging. 

The statement SET (DEBUG, strings, value) deposits the specified value 
in the variable or parameter specified by stringS, 

value 

A value of any data type in VAXTPU. 

The statement SET (DEBUG, string, value) deposits the specified value in 
the global variable, local variable, or parameter named by the string. 

DESCRIPTION 

You use the SET (DEBUG) built-in when you are writing or using user- 
written debuggers. You cannot freely mix parameters when using SET 
(DEBUG). The only valid usages are those shown in the format sections of 
this description. 
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SIGNALED 




ERRORS 

TPU$_NOCURRENTBUF 

WARNING 

There Is no current buffer. 

TPU$_NONAMES 

WARNING 

No names match the one 
requested. 


TPU$_BADKEY 

ERROR 

An unknown keyword has been 
used as an argument. 


TPU$_ARGMISMATCH 

ERROR 

You have specified an 
unsupportecj data type. 


EXAMPLES 

Q SET (DEBUG, ON, "user_remove") 

This statement causes the debugger to be invoked each time the procedure 
"user_remove" is called. 

g SET (DEBUG, PROGRAM, "user_debugger") 

This statement causes the user-written program "user_debugger" to be 
called as the program to help locate programming errors. 

g PROCEDURE debugon 

SET (DEBUG, PROGRAM, "tpu$$debug"); 

BREAK; 

ENDPROCEDURE; 

debugon; 

This procedure and statement from the VAXTPU debugger are compiled 
and executed when the user specifies /DEBUG on the DCL command line. 
The BREAK statement suspends execution of the debugger program emd 
directs the debugger to wait for a debugging command from the user. 

Q SET (DEBUG, "user_x_count", 42); 

This statement sets the value of the variable user_x_count to 42. 
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SET (DEFAULT_DIRECTORY) 



Determines the directory that will be used as the default. 

FORMAT 

Iold_default_string := ] SET (DEFAULT_DIRECTORY, new_default_string) 

PARAMETERS 

DEFAULT_DIRECTORY 

A kejrword indicating that the SET built-in is being used to control which 
directory is used as the default. 

new_default_stnng 

A string naming the directory to which you want the default changed. 

DESCRIPTION 

When the user exits from VAXTPU, the default directory is not restored to 
the default that was set when the user invoked VAXTPU. 

Note that when the user issues the EVE command DCL SHOW DEFAULT, 
the default shown is not always the new default directory, even though the 
setting has actually been changed. To update DCL tracking of the current 
default directory, use the EVE command DCL SET DEFAULT instead of 
calling this built-in procedure directly. 

SIGNALED 

ERRORS 

TPU$__TOOMANY ERROR You specified more than two 

parameters. 

TPU$_TOOFEW ERROR SET (DEFAULT_DIRECTORY) 

requires two parameters. 

TPU$_SYSERROR ERROR One of the system routines used 

has failed. The system routine’s 
error message will be in the 
message buffer. 

TPU$JNVPARAM ERROR The second parameter must be a 

string. 

TPU$_PARSEFAIL WARNING Parameter is not a valid RMS file 

specification. 


EXAMPLE 

prev_dir := SET (DEFAULT_DIRECTORY, "DISKl:[WALSH.PINK]"); 

This statement sets the default directory to [WALSH.PINKI on the device 
DISKl. The variable prev_dir contains the string naming the previous 
default directory. 
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SET (DETACHED_ACTION) 



Specifies the code to be executed when the VAXTPU main input ioop detects 
that the current cursor position is detached (that is, that the cursor position 
cannot accurateiy represent the editing point in the current window). 

FORMAT 

SET (DETACHED_ACTION, SCREEN 
r buffer 
learn 

1, < program > ]) 
range 
. string 

PARAMETERS 

DETACHED_ACTION 

A keyword indicating that the SET built-in is being used to designate the 
detached cursor action routine. 

SCREEN 

A keyword indicating that the detached action routine is being set for all 
buffers and windows used during the session. 

buffer 

The buffer containing the detached cursor action routine. 

learn 

The learn sequence that is executed as the detached cursor action routine. 

program 

The program containing the detached cursor action routine. 

range 

The range containing the detached cursor action routine. 

string 

The string containing the detached cursor action routine. 

DESCRIPTION 

If VAXTPU determines that the current editing point is on a record that 
is not visible in the current window, the screen updater positions the 
cursor on the next visible record, placing the cursor in the comparable 
screen column. This condition is known as a "detached cursor." Use 

SET (DETACHED_ACTION) to designate code to be executed when the 
cursor is detached. 

There are five reasons for a detached cursor. The following table shows 
these reasons, along with their constants and integers. 
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Constant 

Value 

Reason 

TPU$K_OFF_LEFT 

1 

The editing point is off the left side of the current 
window. 

TPU$K_OFF_RIGHT 

2 

The editing point is off the right side of the current 
window. 

TPU$KJNVISIBLE 

4 

The editing point is on a record that is invisible in 
the current window. 

TPU$K_DISJOINT 

8 

The current buffer is not mapped to the current 
window. 

TPU$K UNMAPPED 

16 

No current window exists. 


If you do not specify the optional third parameter, 

SET (DETACHED_ACTION) deletes the current detached action routine. 

To fetch the current detached action routine, use GET_INFO (SCREEN, 
"detached_action"). To find out which of the five possible detached states 
the cursor is in, use GETJNFO (SCREEN, "detached_reason"). 


SIGNALED 

ERRORS 

TPU$_TOOMANY 

ERROR 

You specified too many 
parameters. 


TPU$_TOOFEW 

ERROR 

You specified too few parameters. 


TPU$JNVPARAM 

ERROR 

The second parameter must be a 
keyword. 


TPU$_ARGMISMATCH 

ERROR 

The third parameter must be a 
program or a learn key sequence. 


TPU$_BADKEY 

WARNING 

The second parameter must be 
SCREEN. 


TPU$_COMPILEFAIL 

WARNING 

The third parameter did not 
compile successfully. 


TPU$_COMPILED 

SUCCESS 

The third parameter successfully 
compiled. 
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SET (DETACHED_ACTION) 


EXAMPLE 


PROCEDURE detached_routine 

LOCAL rightmost_column^ 
the__of f set; 

IF GET_INFO (SCREEN, ”detached_reason") < > tpu$k_off_right 
THEN RETURN; 

ENDIF; 


rightmost_column := GET_INFO (CURRENT_WINDOW, "right", VISIBLE_TEXT); 
the_offset := GET_INFO (CURRENT_BUFFER, "offset_column"); 

IF the_offset > rightmost_column 


THEN SHIFT (CURRENT_WINDOW, the_offset - rightmost__column + 2) 
ENDIF; 

UPDATE (CURRENT_WINDOW); 

ENDPROCEDURE; 


Given this definition of the procedure "detached_routine”, the following 
statement designates this procedure as an application’s detached action 
routine: 


SET (DETACHED ACTION, SCREEN, 


"detached routine"); 


This detached action routine shifts the current window to the right if the 
editing point is to the right of the last displayed column. 



7-369 







VAXTPU Built-In Procedures 

SET (DISPLAY_VALUE) 


SET (DISPLAY_VALUE) 



Sets the display value of the specified window. 

FORMAT 

SET (DISPLAY_ VALUE,window,display_valuejnteger) 

PARAMETERS 

DISPLAY_VALUE 

A keyword indicating that the SET built-in is being used to set the display 
value for a window. 

window 

The window whose display value you want to set. 

display_ value_integer 

An integer from -127 to +127. 

DESCRIPTION 

VAXTPU uses a window’s display value, which is an integer value, to 
determine if a given record in a buffer should be made visible in the 
window mapped to the buffer. If the record’s display value is greater than 
or equal to the window’s setting, VAXTPU makes the record visible in that 
window; otherwise, VAXTPU makes the record invisible. 

The record’s display values are set by using the 

SET (RECORD_ATTRIBUTES) built-in procedure. 

SIGNALED 

ERRORS 

TPU$_TOOMANY ERROR You specified too many 

parameters. 

TPU$_TOOFEW ERROR You specified too few parameters. 

TPU$JNVPARAM ERROR The second parameter must be a 

window. 

TPU$_BADDISPVAL WARNING Display values must be between 

-127 and +127. 


EXAMPLE 

SET (DISPLAY_VALUE, CURRENT_WINDOW, 10); 

This statement gives the current window a display value of 10. This 
means that any record whose display value is less than 10 is invisible in 
the specified window. 
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SET (DRI\/I_HIERARCHY) 

Sets the User Interface Definition (UID) file or files to be used with VAXTPU. 


FORMAT integer := SET (DRM_HIERARCHY, fUespec 

[, fUespec... ]) 


PARAMETERS fllespec 

A string specifying the UID file to be used. VAXTPU applies the VMS 
default file specification "SYS$LIBRARY: .UID" to the string you pass to 
SET (DRM_HIERARCHY). You must specify at least one file name. 


return valUG An integer that is the identification number for the XUI Resource Manager 

hierarchy. 


DESCRIPTION Using UID files to specify hierarchies makes it easy to translate the 

product into other languages and to modify an application’s interface 
without recompiling all the code implementing the application. 

For more information about UID files, see the VMS DECwindows Guide to 
Application Programming. 


SIGNALED 

ERRORS 

TPU$_ARGMISMATCH 

ERROR 

The data type of the indicated 
parameter is not supported by the 
SET {DRM_HIERARCHY) built-in. 


TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
SET (DRM_HIERARCHY) built-in. 


TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the SET (DRM_HIERARCHY) 
built-in. 


TPU$_FAILURE_STATUS 

ERROR 

The Digital Resource Manager 
returned an error status. 


TPU$JNVPARAM 

ERROR 

You specified an invalid parameter. 


TPU$_REQUIRESDECW 

ERROR 

Requires the VAXTPU 
DECwindows screen updater. 


EXAMPLE The following statement designates the User Interface Definition (UID) 

file MYNODE$DUAO:[SMITH]EXAMPLE.UID as a file to be used with 
VAXTPU to create widgets needed by the layered application: 

example_hierarchy := SET (DRM_HIERARCHY, "mynode$duaO:[smith]example.uid") ; 

For examples of how the SET (DRM_HIERARCHY) built-in is used in 
procedures, see Example B—1 and Example B—2. 
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SET (ENABLE_RESIZE) 

Enables or disables resizing of the VAXTPU screen. 

FORMAT 

SET (ENABLE_RESIZE, }; 

PARAMETERS 

ENABLE_RESIZE 

A keyword directing VAXTPU to enable or disable screen resizing. 

ON 

A ke3rword enabling screen resizing. 

OFF 

A keyword disabling screen resizing. 

DESCRIPTION 

If you specify the ON keyword, VAXTPU gives the DECwindows window 
manager hints (parameters that the window manager is free to use or 
ignore) on the allowable maximum and minimum sizes for the VAXTPU 
screen. The hints are set by the SET (SCREEN_LIMITS, array) built-in. 

If you specify the OFF keyword, VAXTPU uses the screen’s current width 
and length as the maximum and minimum size. 


SIGNALED 

ERRORS 


TPU$_BADKEY 

WARNING 

You specified an invalid keyword 
as a parameter. 

TPU$JNVPARAM 

ERROR 

One of the parameters was 
specified with data of the wrong 
type. 

TPU$_NORETURNVALUE 

ERROR 

SET (ENABLE_RESIZE) cannot 
return a value. 

TPU$_REQUIRESDECW 

ERROR 

You can use the SET (ENABLE^ 
RESIZE) built-in only if you are 
using DECwindows VAXTPU. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
SET (ENABLE^RESIZE) built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed 
to the SET (ENABLE^RESIZE) 
built-in. 
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EXAMPLE 

SET (ENABLE_RESIZE, 


ON) ; 

This statement enables screen resizing, lb see this statement used in 
an initializing procedure, see the example in the description of the SET 
(SCREEN_LIMITS) built-in. 
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SET (EOB_TEXT) 


FORMAT 

SET (EOB_TEXT, buffer, string) 

PARAMETERS 

EOB_TEXT 

A keyword indicating that SET is to determine the text displayed at the 
end of a buffer. This text is merely a visual marker in a buffer and does 
not become part of the file that is written when a buffer is saved. 

The default end-of-buffer text is “[EOB].” 

buffer 

The buffer in which the text for the end-of-buffer is being set. 

String 

The text that is displayed to indicate the end-of-buffer. 

DESCRIPTION 

You may specify ranges that include the end-of-buffer text, but you cannot 
set the record_attributes of the end-of-buffer "record." Therefore, the end- 
of-buffer text is always visible, is left-justified on the screen, and cannot be 
modified using normal editing operations. 

Setting a blank EOB_TEiXT is the only way to "remove" the end-of-buffer 
text. Note, however, that a blank line will still remain. 

SIGNALED 

ERRORS 

TPU$_TOOFEW ERROR This SET built-in requires three 

parameters. 

TPU$_TOOMANY ERROR You specified more than three 

parameters. 

TPU$_INVPARAM ERROR One or more of the specified 

parameters have the wrong type. 

TPU$_FAILURE FATAL VAXTPU couid not create the 

record for the EOB text. 


EXAMPLE 

SET (EOB_TEXT, main_buffer, "[END OF MAIN EDITING BUFFER]") 

This statement causes [END OF MAIN EDITING BUFFER] to be 
displayed as the end-of-buffer text for the main buffer. 
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SET (ERASE_UNMODIFIABLE) 



Controls whether VAXTPU erases unmodifiable records in response to built- 
ins that delete lines from a buffer. 

FORMAT 

{ Qpp } := SET (ERASE_UNMODIFIABLE, buffer { }; 

PARAMETERS 

ERASE_UNMODinABLE 

A keyword indicating that the SET built-in is being used to control 
whether unmodifiable records are deleted in response to built-ins that 
erase lines in a buffer. 

buffer 

The buffer for which you want to turn on or turn off erasing of 
unmodifiable records. 

ON 

A keyword enabling erasing of unmodifiable records. 

OFF 

A keyword disabling erasing of unmodifiable records. 

return value 

The keyword ON or OFF, indicating the previous setting of ERASE. 
UNMODIFIABLE. 

DESCRIPTION 

By default, unmodifiable records can be deleted from buffers by built- 
ins such as ERASE.LINE. For example, ERASE.LINE deletes an 
immodifiable record only if ERASE.UNMODIFIABLE is turned on. If 
ERASE.UNMODIFIABLE is turned off when ERASE.LINE or a similar 
built-in encoimters an unmodifiable record, the built-in returns an error 
and does not delete the record. 

However, some built-ins delete records as a side effect of their normal 
action. Table 7-10 shows the built-ins that can delete records as 
a side effect and shows what these built-ins do instead when the 
ERASE.UNMODIFIABLE setting is turned off. The SET (ERASE. 
UNMODIFIABLE) built-in prevents these built-ins from unintentionally 
deleting unmodifiable records. 
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Table 7-10 Selected Built-In Actions When ERASE_UNMODIFIABLE Is 
Turned Off 


Built-in 

Action 

APPEND_LINE 

Signals a warning if an attempt is made to append to an 
unmodifiable line. 

CHANGE_CASE 

Signals a warning if any of the lines in the range or buffer are 
unmodifiable. 

COPY_TEXT 

Copies all records, preserving modifiability attribute while In 
insert mode. 

Signals a warning if the current editing position is In an 
unmodifiable line. 

Signals a warning if in overstrike mode and any of the lines 
to be overstruck are unmodifiable. 

EDIT 

Signals a warning if any of the lines in the range or buffer are 
unmodifiable. 

ERASE (buffer) 
ERASE (range) 

Signals a warning if any line in the buffer is unmodifiable. 

Signals a warning if the start or the end of the range is in the 
middle of an unmodifiable line. 

Signals a warning if any of the lines in the range are 
unmodifiable. 

ERASE 

CHARACTER 

ERASE_LINE 

FILL 

Signals a warning if the current character is unmodifiable. 

Signals a warning if the current line is unmodifiable. 

Signals a warning if any of the lines in the range or buffer are 
unmodifiable. 

MOVE_TEXT 

Moves all records, preserving modifiability attribute while in 
insert mode. 

Signals a warning if the current editing point is in an 
unmodifiable line. 

Signals a warning if in overstrike mode and any of the lines 
to be overstruck are unmodifiable. 

If the start or the end of the range is In the middle of an 
unmodifiable line, the MOVE__TEXT is turned into a COPY__ 
TEXT and a warning is issued. 

If any of the lines in the buffer or range are unmodifiable, the 
MOVE__TEXT is turned into a COPY_TEXT and a warning Is 
issued. 

SPLIT_LINE 

Signals a warning if the current editing position is in the 
middle of an unmodifiable line. 

If the current editing position is at the beginning of an 
unmodifiable line, a new modifiable line is created before It. 

If the current editing position is at the end of an unmodifiable 
line, a new modifiable line is created after It. 


(continued on next page) 
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Table 7-10 (Cent.) 

Selected Built-In Actions When ERASE_ 
UNMODIFIABLE is Turned Off 

Built-in 

Action 

TRANSLATE 

If the current editing position is on an empty unmodifiable 
line, then a new modifiable line is created after it. 

Signals a warning if any of the lines in the range or buffer are 
unmodifiable. 


SET (ERASE_UNMODIFIABLE) optionally returns an integer (0 or 1) 
indicating whether ERASE_XJNMODIFIABLE was turned on before the 
current call was executed. This makes it easier to return to the previous 
setting later in the program. 


SIGNALED 

ERRORS 

TPU$_TOOMANY 

ERROR 

You specified too many 
parameters. 


TPU$_TOOFEW 

ERROR 

You specified too few parameters. 


TPUSJNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 


TPU$_BADKEY 

WARNING 

The third parameter must be ON 
or OFF. 


EXAMPLE 

old_setting := SET (ERASE_UNMODIFIABLE, CURRENT_BUFFER, OFF); 

This statement turns off erasing of unmodifiable records in the current 
buffer and returns the previous setting of ERASE_UNMODIFIABLE. 
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SET (FACILITY_NAME) 


FORMAT SET (FACILITY_NAME, string) 


PARAMETERS FACIUTY_NAME 

The facility n 2 ime that is the first item in a message generated by 
VAXTPU. 

String 

The string that you specify as the facihty name for messages. The 
maximum length of this name is 10 characters. 


SIGNALED 

ERRORS 

TPU$_FACTOOLONG 

WARNING 

Name specified is ionger than 
maximum aiiowed. 


TPU$_MINVALUE 

WARNING 

Argument specified is iess than 
the minimum aiiowed. 


TPU$_ARGMISMATCH 

ERROR 

The second parameter must be a 
string. 


TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 


EXAMPLE 

SET (FACILITY_NAME, "new_editor") 

This statement causes "new_editor" to be used as the facility name in 
messages. 
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SET (FORWARD) 


FORMAT 

SET (FORWARD, buffer) 

PARAMETERS 

FORWARD 

A keyword specifying the direction of the buffer. FORWARD means to go 
toward the end of the buffer. 

The default direction for a buffer is forward. 

buffer 

The buffer whose direction you want to set. 

DESCRIPTION 

The editor uses this feature to keep track of direction for searching or 
movement. 

SIGNALED 

ERRORS 

TPU$_TOOFEW ERROR SET (FORWARD) requires two 

parameters. 

TPU$_TOOMANY ERROR You specified more than two 

parameters. 

TPU$_INVPARAM ERROR One or more of the specified 

parameters have the wrong type. 

TPU$_BADKEY ERROR You specified an invalid keyword. 


EXAMPLE 

SET (FORWARD, my_buffer) 

T his statement causes the direction of the buffer to be toward the end of 
the buffer. 
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SET (GLOBAL_SELECT) 



Requests ownership of the specified global selection property. 

FORMAT 

f PRIMARY 'I 

[ integer := ] SET (GLOBAL_SELECT. SCREEN, 1 SECONDARY J; 

1 selection_name ) 

PARAMETERS 

GLOBALJSELECT 

A keyword indicating that the subject of the information request is a 
global selection. 

SCREEN 

A keyword used to preserve compatibility with future versions of VAXTPU. 

PRIMARY 

A keyword directing VAXTPU to request ownership of the primary global 
selection. 

SECONDARY 

A keyword directing VAXTPU to request ownership of the secondary global 
selection. 

selection_name 

A string naming the global selection whose ownership VAXTPU is to 
request. 

return value 

The value 1 if the global selection ownership request was granted; 0 
otherwise. 

DESCRIPTION 

SET (GLOBAL_SELECT) returns the integer 1 if the request for 
ownership of a global selection was granted; otherwise 0. 

The last parameter identifies the global selection of which VAXTPU is to 
grab ownership. 

VAXTPU is notified immediately if its request is granted. Therefore, 
VAXTPU does not automatically execute the global selection grab routine 
when it encounters SET (GLOBAL_SELECT). VAXTPU executes the 
routine only when it automatically grabs the primary selection after it 
receives input focus. 

For more information about the concept of global selection, see the XUI 
Style Guide, 
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SIGNALED 

ERRORS 


EXAMPLE 

SET (GLOBAL_SELECT, 


TPU$_BADKEY 

WARNING 

You specified an invalid keyword 
as a parameter. 

TPU$_INVPARAM 

ERROR 

One of the parameters was 
specified with data of the wrong 
type. 

TPU$_REQUIRESDECW 

ERROR 

You can use the SET (GLOBAL_ 
SELECT) built-in only if you are 
using DECwindows VAXTPU. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
SET (GLOBAL_SELECT) built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the SET (GLOBAL_SELECT) 
built-in. 


SCREEN, PRIMARY); 

This statement requests ownership of the primary global selection. For 
another example of code using the SET (GLOBAL_SELECT) built-in, see 
Example B-10. 
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SET (GLOBAL_SELECT_GRAB) 



Specifies the program or learn sequence VAXTPU should execute whenever it 
automatically grabs ownership of the primary selection. 

FORMAT 

SET (GLOBAL_SELECT_GRAB, SCREEN 
( buffer 
learn sequence 

1 P''°9ram 
range 
string 

1 NONE j 

PARAMETERS 

GLOBAL_SELECT_GRAB 

A keyword indicating that the subject of the information request is a 
global select grab routine. 

SCREEN 

A ke 3 rword used to preserve compatibility with future versions of VAXTPU. 

buffer 

The buffer that contains the grab routine. 

learnjsequence 

The learn sequence specifying the grab routine. 

program 

The program specifying the grab routine. 

range 

The range that contains the grab routine. 

String 

The string that contains the grab routine. 

NONE 

A keyword directing VAXTPU to delete the current global selection 
grab routine. This is the default if you do not specify the optioned third 
parameter. 

DESCRIPTION 

For more information about VAXTPU global selection support, see 

Chapter 4. 

If the optional parameter is not specified, NONE is the default. When 
NONE is specified or used by default, VAXTPU deletes the current global 
selection grab routine. When no global selection grab routine is defined, 
your application is not informed when VAXTPU grabs the primary global 
selection. 
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SIGNALED 

ERRORS 


EXAMPLE 

SET (GLOBAL_SELECT 
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TPU$_BADKEY 

WARNING 

You specified an invalid keyword 
as a parameter. 

TPU$JNVPARAM 

ERROR 

One of the parameters was 
specified with data of the wrong 
type. 

TPU$_NORETURNVALUE 

ERROR 

SET (GLOBAL_SELECT_GRAB) 
cannot return a value. 

TPU$_REQUIRESDECW 

ERROR 

You can use the SET (GLOBAL_ 
SELECT_GRAB) built-in only 
if you are using DECwindows 
VAXTPU. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
SET (GLOBAL_SELECT_GRAB) 
built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the SET (GLOBAL_SELECT_ 
GRAB) built-in. 


GRAB, SCREEN, "user_grab_global") ; 


This statement designates the procedure user_grab_glohal as a global 
selection read routine. 

For another example of code using the SET (GLOBAL_SELECT_GRAB) 
built-in, see Example 7-1. 

Sample Code Setting Various Global Selection and Input Focus Routines 

Example 7-1 shows possible ways that a layered application can use 
statements setting global selection and input focus routines. The example 
contains portions of the procedure eve$mouse_module_init. You can find 
the original version in SYS$EXAMPLES:EVE$MOUSE.TPU. For more 
information about using the files in SYS$EXAMPLES as examples, see 
Section B.l. 

The statements in Example 7-1 designate EVE’s global selection read 
routine, global selection grab routine, global selection ungrab routine, 
input focus grab routine, and input focus ungrab routine. 
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Example 7-1 initialization Procedure Using Variants of the SET Built-in 


PROCEDURE eve$mouse module init 


IF GET_INFO (SCREEN, "decwindows") 
THEN 


SET (GLOBAL_SELECT_READ, SCREEN, "eve$write_global_select"); 

SET (GLOBAL_SELECT_UNGRAB, SCREEN, "eve$global_select_ungrab"); 
SET (GLOBAL_SELECT_GRAB, SCREEN, "eve$global_select_grab"); 

SET (INPUT_FOCUS_GRAB, SCREEN, "eve$input_focus_grab"); 

SET (INPUT_FOCUS_UNGRAB, SCREEN, "eve$input_focus_ungrab"); 
ENDIF; 


ENDPROCEDURE; 
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SET (GLOBAL_SELECT_READ) 



Specifies the program or iearn sequence VAXTPU shouid execute whenever it 
receives a seiection request event on a globai seiection it owns. 

FORMAT 

SET (GLOBAL_SELECT_READ, { } 

' buffer2 
learn sequence 

1 Ij) 

range 

string 

1 NONE J 

PARAMETERS 

GLOBAL_SELECT_READ 

A keyword indicating that the subject of the information request is a 
global select read routine. 

bufferl 

The buffer with which the global selection read routine is to be associated. 

SCREEN 

A keyword indicating that the specified routine is to be the application’s 
default global selection read routine. 

buf1er2 

The buffer that contains the global selection read routine. 

Ieam_sequence 

The learn sequence that specifies the global selection read routine. 

program 

The program that specifies the global selection read routine. 

range 

The range that contains the global selection read routine. 

String 

The string that contains the global selection read routine. 

NONE 

A keyword indicating that the global selection read routine should be 
deleted. 

If you do not specify the optional third parameter, NONE is the default. 
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DESCRIPTION To specify a buffer-specific global selection read routine, use the bufferl 

parameter. To specify a global selection read routine for the entire 
application, use the SCREEN keyword. 

When VAXTPU receives a request for information about a global selection 
it owns, it checks to see if the current buffer has a global selection read 
routine. If so, it executes that routine. If not, it checks to see if there is 
an application-wide global selection read routine. If so, it executes that 
routine. If not, it tries to respond to the request itself. 

If the optional parameter is not specified, NONE is the default. When 
NONE is specified or used by default, VAXTPU deletes the current global 
selection read routine. 


SIGNALED 

ERRORS 


TPU$_BADKEY 

WARNING 

You specified an invalid keyword 
as a parameter. 

TPU$JNVPARAM 

ERROR 

One of the parameters was 
specified with data of the wrong 
type. 

TPU$_NORETURNVALUE 

ERROR 

SET (GLOBAL_SELECT_READ) 
cannot return a value. 

TPU$_REQUIRESDECW 

ERROR 

You can use the SET (GLOBAL 
SELECT_READ) built-in only 
if you are using DECwindows 
VAXTPU. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
SET (GLOBAL_SELECT_READ) 
built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the SET (GLOBAL_SELECT_ 
READ) built-in. 


EXAMPLE 

SET (GLOBAL_SELECT_READ, SCREEN, "user_read_global'') ; 

The following statement designates the procedure userjread_global as a 
global selection read routine. For another example of code using the SET 
(GLOBAL_SELECT_READ) built-in, see Example 7-1. 
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SET (GLOBAL_SELECT_TIME) 

Specifies how long VAXTPU should wait before it assumes that a request for 
information about a global selection will not be satisfied. 


FORMAT 


SET (GLOBAL_SELECT_TIME, SCREEN. | | 


PARAMETERS GLOBAL_SELECT_TIME 

A keyword directing VAXTPU to set the expiration time for a global 
selection information request. 

SCREEN 

A keyword used to maintain compatibility with future versions of 
VAXTPU. 

integer 

The number of seconds that VAXTPU should wait. 

String 

A string in VMS delta time format indicating how long VAXTPU should 
wait. 


DESCRIPTION The default waiting time is set by DECwindows. The maximum waiting 

time you can set is 24 days, 20 hours. 


SIGNALED 

ERRORS 


TPU$_BADKEY 

WARNING 

You specified an invalid keyword 
as a parameter. 

TPU$_INVT1ME 

WARNING 

You specified an invalid time 
interval. 

TPU$JNVPARAM 

ERROR 

One of the parameters was 
specified with data of the wrong 
type. 

TPU$_NORETURNVALUE 

ERROR 

The SET (GLOBAL_SELECT_ 
TIME) built-in cannot return a 
value. 

TPU$_REQUIRESDECW 

ERROR 

You can use the SET (GLOBAL_ 
SELECT_TIME) built-in only if you 
are using DECwindows VAXTPU. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
SET (GLOBAL_SELECT_TIME) 
built-in. 
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EXAMPLE 

SET (GLOBAL SELECT 


TPU$_TOOMANY ERROR Too many arguments passed to 

the SET (GLOBAL_SELECT_ 
TIME) built-in. 


TIME, SCREEN, 3); 

This statement sets the waiting time for a global selection response to 3 
seconds. 
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SET (GLOBAL_SELECT_UNGRAB) 



Specifies the program or learn sequence VAXTPU should execute whenever it 
loses ownership of a selection. 

FORMAT 

SET (GLOBAL_SELECT_UNGRAB, SCREEN 
( buffer 
learnjsequence 
r i P^° 9 ram 1 .. 

range 
string 

1 NONE J 

PARAMETERS 

GLOBAL_SELECT_UNGRAB 

A ke 5 rword indicating that the subject of the information request is a 
global select ungrab routine. 

SCREEN 

A keyword used to preserve compatibility with future versions of VAXTPU. 

buffer 

The buffer that contains the global selection ungrab routine. 

learnjsequence 

The learn sequence that specifies the global selection ungrab routine. 

program 

The program that specifies the global selection ungrab routine. 

range 

The range that contains the global selection ungrab routine. 

String 

The string that contains the global selection ungrab routine. 

NONE 

A keyword directing VAXTPU to delete the current global selection 
ungrab routine. This is the default if you do not specify the optional 
third parameter. 

DESCRIPTION 

For more information about VAXTPU global selection support, see 
Chapter 4. 

If the optional parameter is not specified, NONE is the default. When 
NONE is specified or used by default, VAXTPU deletes the current global 
selection ungrab routine. When no global selection ungrab routine is 
defined, your application is not informed when VAXTPU loses ownership 
of the primary global selection. 
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SIGNALED 

ERRORS 


EXAMPLE 

SET (GLOBAL SELECT 


TPU$_BADKEY 

WARNING 

You specified an invalid keyword 
as a parameter. 


TPU$_INVPARAM 

ERROR 

One of the parameters was 
specified with data of the wrong 
type. 


TPU$_NORETURNVALUE 

ERROR 

SET (GLOBAL_SELECT_ 

UNGRAB) cannot return a value. 


TPU$_REQUIRESDECW 

ERROR 

You can use the SET (GLOBAL 
SELECT_UNGRAB) built-in only 
if you are using DECwindows 
VAXTPU. 


TPU$_TOOFEW 

ERROR 

Too few arguments passed to 
the SET (GLOBAL SELECT 
UNGRAB) built-in. 

• 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the SET (GLOBAL SELECT 
UNGRAB) built-in. 



ONGRAB, SCREEN, "user_ungrab_global"); 


This statement designates the procedure user_ungrab_global as a global 
selection ungrab routine. For another example of code using the SET 
(GLOBAL_SELECT_UNGRAB) built-in, see Example 7-1, following the 
description of the SET (GLOBAL_SELECT_GRAB) built-in. 
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SET (HEIGHT) 

Sets the height of the VAXTPU screen without modifying the height or iocation 
of any VAXTPU window. 


FORMAT SET (HEIGHT, SCREEN, length) 


PARAMETERS HEIGHT 

A ke 3 rword indicating that the vertical dimension is being set. 

SCREEN 

A keyword indicating that the screen is being resized. 

length 

The length (in lines) that you want the screen to have. The value must be 
an integer between 1 and 255. 


Q£3CRIPTiON Although SET (HEIGHT) does not alter any VAXTPU windows, the default 

EVE behavior when the screen is made smaller is to unmap windows from 
the screen, starting with the bottom-most window and working upward, 
until there is room on the screen for the remaining windows. If the screen 
is subsequently made larger, the unmapped windows are not remapped by 
default. 


SIGNALED 

ERRORS 

TPU$_TOOMANY 

ERROR 

You specified more than three 
parameters. 


TPU$_TOOFEW 

ERROR 

SET (HEIGHT) requires three 
parameters. 


TPU$_INVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 


TPU$_BADKEY 

WARNING 

The second parameter must be 
SCREEN. 


TPU$ 

BADLENGTHCHANGE 

WARNING 

The terminal’s characteristics will 
not allow the height of the screen 
to change. 


TPU$_BADVALUE 

ERROR 

The terminal cannot be set to the 
requested height. 


EXAMPLE 

SET (HEIGHT, SCREEN, 20); 

This statement causes the screen to have a height of 20 lines. 
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SET (ICON_NAME) 



Designates the string used as the layered application’s name in the 
DECwindows icon box. 

FORMAT 

SET (ICON_NAME, string) 

PARAMETERS 

ICON_NAME 

A keyword instructing VAXTPU to set the text of an icon. 

string 

The text you want to appear in the icon. 

SIGNALED 

ERRORS 

TPU$_INVPARAM ERROR One of the parameters was 

specified with data of the wrong 
type. 

TPU$_NORETURNVALUE ERROR SET (ICON_NAME) cannot return 

a value. 

TPU$_REQUIRESDECW ERROR You can use the SET (ICON_ 

NAME) built-in only if you are 
using DECwindows VAXTPU. 

TPU$_TOOFEW ERROR Too few arguments passed to the 

SET (ICON_NAME) built-in. 

TPU$_TOOMANY ERROR Too many arguments passed to 

the SET (ICON_NAME) built-in. 


EXAMPLE 

SET (ICON_NAME, "WordMonger”); 

This statement sets the text naming the layered application to be the 
string WordMonger, 
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SET (ICON_PIXMAP) 



Determines the pixmap the application uses to create its icon in the 
DECwindows icon box if the user has selected the Large Window Manager 
Icon Style. 

FORMATS 

SET (ICON_PIXMAP,integer,iconjjixmap [.widget]) 

or 

SET (iCON_PiXMAP,bitmap_fiie_name [widget]) 

PARAMETERS 

ICON_PIXMAP 

A keyword indicating that the SET built-in is being used to determine the 
pixmap the application uses to create its icon in the DECwindows icon box 
if the user has selected the Large Window Manager Icon Style. 

integer 

The hierarchy identifier returned by the SET (DRM_HIERARCHY) built- 
in. This identifier is passed to the XUI Resource Manager, which uses the 
identifier to find the hierarchy’s resource name in the resource database. 

iconjyixmap 

A case-sensitive string that is the name assigned to the icon in the UIL 
file defining the icon pixmap. The icon must be declared EXPORTED in 
the UIL file. 

widget 

The widget whose icon pixmap is to be set. By default, VAXTPU sets the 
icon pixmap of its top-level widget. 

bitmap_fiie_name 

The file specification of a bitmap file. SET (ICON_PIXMAP) requires these 
files to be in the format created by the Xlib routine WRITE BITMAP 
FILE. To create a file with the correct format, you can use the program 
SYS$SYSTEM:DECW$PAINT.EXE (the DECpaint application) or the 
program DECW$EXAMPLES:BITMAP.EXE. If you use DECpaint, use the 
Customize Picture Size option to set the picture size to nonstandard, the 
width to 32 pixels, and the height to 32 pixels. Use the Zoom option to 
manipulate this small image. Choose the Xll format when you save the 
file. 

DESCRIPTION 

To specify an icon pixmap defined in a UIL file, use the first format variant 
shown in the Format section. To specify an icon created in a bitmap file, 
use the second format variant shown in the Format section. 
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If an application uses SET (ICON_PIXMAP) so a large icon can be 
displayed, in most cases the application should also use SET (ICONIFY_ 
PIXMAP) to create an iconify button in the title bar. An application also 
needs to use SET (ICONIFY_PIXMAP) so a small icon can be displayed if 
the user selects the Small Window Manager Icon Style from the Session 
Manager’s Customize Window dialog box. 


SIGNALED 

ERRORS 

TPU$_FAILURE_STATUS 

ERROR 

The Digital Resource Manager 
returned an error status. 


TPU$JNVPARAM 

ERROR 

One of the parameters was 
specified with data of the wrong 
type. 


TPU$_NORETURNVALUE 

ERROR 

Built-in does not return a value. 


TPU$_REQUIRESDECW 

ERROR 

Requires the VAXTPU 
DECwindows screen updater. 


TPU$_TCX5FEW 

ERROR 

You specified too few parameters. 


TPU$_TOOMANY 

ERROR 

You specified too many 
parameters. 

EXAMPLE 




SET (ICON__PIXMAP, 

"DISKl:[SMITH]ICON_FLAMINGO. 

.Xll") 



This statement causes the icon pixmap stored in the file ICON_ 
FLAMINGO.X11 to be displayed in the application’s icon if the Large 
Window Manager Icon Style has been selected. 
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SET (ICONIFY_PIXMAP) 



Determines the pixmap the application uses to create its icon in the 
DECwindows icon box if the user has selected the Small Window Manager 
Icon Style. When you use SET (ICONIFY_PIXMAP), VAXTPU also 
automatically places the specified pixmap in the application’s iconify button, in 
the title bar. 

FORMATS 

SET (ICONIFY_PIXMAP,integer,icon_pixmap [,widget]) 

or 

SET (iCONiFY_PiXMAP,bitmapJiie_name [.widget]) 

PARAMETERS 

ICONIFY_PIXMAP 

A keyword indicating that the SET built-in is being used to determine the 
pixmap the application uses to create its icon in the DECwindows icon box 
if the user has selected the Small Window Manager Icon Style. 

integer 

The hierarchy identifier returned by the SET (DRM_HIERARCHY) built- 
in. This identifier is passed to the XUI Resource Manager, which uses the 
identifier to find the hierarchy’s resource name in the resource database. 

iconjjixmap 

A case-sensitive string that is the name assigned to the icon in the UIL 
file defining the iconify pixmap. The icon must be declared EXPORTED in 
the UIL file. 

widget 

The widget whose iconify pixmap is to be set. By default, VAXTPU sets 
the iconify pixmap of its top-level widget. 

bitmap_fiie_name 

The file specification of a bitmap file. SET (ICONIFY_PIXMAP) requires 
these files to be in the format created by the Xlib routine WRITE BITMAP 
FILE. To create a file with the correct format, you can use the program 
SYS$SYSTEM:DECW$PAINT.EXE (the DECpaint application) or the 
program DECW$EXAMPLES:BITMAP.EXE. If you use DECpaint, use the 
Customize Picture Size option to set the picture size to non-standard, the 
width to 16 pixels, and the height to 16 pixels. Use the Zoom option to 
manipulate this small image. Choose the Xll format when you save the 
file. 
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DESCRIPTION To specify an iconify pixmap defined in a UIL file, use the first format 

variant shown in the Format section. To specify an icon created in a 
bitmap file, use the second format variant shown in the Format section. 

If an application uses SET (ICONIFY_PIXMAP) so a small icon can be 
displayed, in most cases the application should also use SET (ICON_ 
PIXMAP) so a large icon can be displayed if the user selects the Large 
Window Manager Icon Style. 

Note that the user selects the Large or Small Window Manager Icon Style 
using the Session Manager’s Customize Window dialog box. 


SIGNALED 

ERRORS 

TPU$_FAILURE_STATUS 

ERROR 

The Digital Resource Manager 
returned an error status. 


TPU$JNVPARAM 

ERROR 

One of the parameters was 
specified with data of the wrong 
type. 


TPU$_NORETURNVALUE 

ERROR 

Built-in does not return a value. 


TPU$_REQUIRESDECW 

ERROR 

Requires the VAXTPU 
DECwindows screen updater. 


TPU$_TOOFEW 

ERROR 

You specified too few parameters. 


TPU$_TOOMANY 

ERROR 

You specified too many 
parameters. 


EXAMPLE 

SET (ICONIFY_PIXMAP, "DISKl:[SMITH]ICONIFY_FLAMINGO.Xll") 

This statement causes the iconify pixmap stored in the file ICONIFY_ 
FLAMINGO-Xll to be displayed in the apphcation’s iconify button and in 
the application’s icon if the small Window Manager Icon Style has been 
selected. 
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SET (INFORMATIONAL) 


FORMAT 

SET (INFORMATIONAL, { 

PARAMETERS 

INFORMATIONAL 

Informational messages that VAXTPU writes. 

ON 

Causes the informational messages to be displayed. 

OFF 

Suppresses the display of informational messages. 

DESCRIPTION 

If you specify a section file when invoking VAXTPU (either by default, or 
by using the qualifier /SECTION), VAXTPU may not display informational 
messages. You can cause informational messages to be written by using 
SET (INFORMATIONAL, ON). 

If you use the qualifier /NOSECTION when invoking VAXTPU, 
informational messages are written by default. 

When you are developing VAXTPU programs, the informational messages 
help you find errors in your program, so it is a good idea to use the built-in 
procedure SET (INFORMATIONAL) to cause the messages to be displayed. 

See Appendix D for a list of the VAXTPU informational messages. 

SIGNALED 

ERRORS 

TPU$_TOOFEW ERROR SET (INFORMATIONAL) requires 

two parameters. 

TPU$_TOOMANY ERROR You specified more than two 

parameters. 

TPU$_INVPARAM ERROR One or more of the specified 

parameters have the wrong type. 

TPU$_BADKEY ERROR You specified an invalid keyword. 


EXAMPLE 

SET (INFORMATIONAL, OFF) 

This statement causes the display of informational messages to be turned 
off. 
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SET (INPUT_FOCUS) 



Requests ownership of the input focus. Ownership of the input focus 
determines which appiication or widget processes user input from the 
keyboard. 

FORMAT 

SET (INPUT_FOCUS ' ) 

PARAMETERS 

INPUT_FOCUS 

A keyword directing VAXTPU to assign the input focus. 

SCREEN 

An optional keyword indicating that the top-level widget associated with 
VAXTriPs screen is to receive the input focus. This keyword is the default. 

widget 

The widget that is to receive the input focus. Note that if you specify a 
widget for this parameter, the VAXTPU key bindings are not available to 
process keyboard input into the specified widget. 

DESCRIPTION 

This built-in requests that input focus be given to VAXTPU or to a widget 
that is part of an application layered on VAXTPU. It does not guarantee 
that VAXTPU or the widget gets the input focus. If VAXTPU or the widget 
receives the input focus, it gets a focus-in event. When VAXTPU gets this 
event, it calls the input focus grab routine. For more information about 
the role of events in DECwindows applications, see the VMS DECwindows 
Guide to Application Programming. 

When the top-level widget for VAXTPU’s screen has the input focus, 
VAXTPU processes keystrokes normally. That is, undefined printable keys 
insert characters in the current buffer, and defined keys execute the code 
bound to them. 

If a child widget in the widget hierarchy has the input focus, keystrokes 
are processed by that widget. For example, when a text widget in EVE’s 
replace dialog box has the input focus, keystrokes are processed by the 
text widget, not by VAXTPU. No VAXTPU key bindings are in effect. 

SIGNALED 

ERRORS 

TPU$_BADKEY warning You specified an invalid keyword 

as a parameter. 

TPU$_INVPARAM ERROR One of the parameters was 

specified with data of the wrong 


type. 
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TPU$_NORETURNVALUE 

ERROR 

SET (INPUT_FOCUS) cannot 
return a value. 

TPU$_REQUIRESDECW 

ERROR 

You can use the SET (INPUT_ 
FOCUS) built-in only if you are 
using DECwindows VAXTPU. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
SET (INPUT_FOCUS) built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the SET (INPUT_FOCUS) built-in. 


EXAMPLE 

PROCEDURE eve$$widget_replace_ok 

LOCAL new_string, 
old_string, 
o 1 d_s t r_t ext__wi dge t, 
new_st r_text_widget; 


SET (INPUT_FOCUS); ! This statement grabs input focus 

! so CTRL/C events will be detected. 

! Get the replace strings from the eve$$k_replace_new__[old]text widgets. 

old_str__text_widget := GET___INFO (WIDGET, "widget_id", eve$x_replace__dialog, 

"REPLACE_DIALOG.REPLACE_OLD_TEXT") 

old_string := GET__INFO (old_str_text__widget, "text"); 

! Test only the old string. 

IF old_string = "" 

THEN 

eve$message (EVE$_NOREPLSTR); 

RETURN; 

ENDIF; 

new_str_text_widget := GET_INFO (WIDGET, "widget_id", eve$x_replace_dialog, 

"REPLACE_DIALOG.REPLACE_NEW_TEXT") 

new_string := GET__INFO (newestr_text_widget, "text"); 

IF new_string = "" 

THEN 

eve$$replacel (old_string, new_string, 1); 

ELSE 

eve$$replacel (old_string, new__string) ; 

ENDIF; 

ENDPROCEDURE; 


This procedure shows one possible way that a layered application can use 
the SET (INPUT_FOCUS) built-in. The procedure is a modified version 
of the EVE procedure EVE$$WIDGET_REPLACE_OKAY. You can find 
the original version in SYS$EXAMPLES:EVE$MENUS.TPU. For more 
information about using the files in SYS$EXAMPLES as examples, see 
Section B.l. 

Procedure EVE$$WIDGET_REPIACE_OK fetches and tests the user’s 
responses to prompts for old and new replace strings. 
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SET (INPUT_FOCUS_GRAB) 



Specifies the program or iearn sequence that VAXTPU shouid execute 
whenever it processes a focus-in event. 

FORMAT 

' buffer 

learn_sequence 

SET (INPUT_FOCUS_GRAB, SCREEN 1 ^ 

string 

1 NONE J 

PARAMETERS 

INPUT_FOCUS_GRAB 

A keyword directing VAXTPU to set an attribute related to an input focus 
grab routine. 

SCREEN 

An keyword used for compatibility with future versions of VAXTPU. 

buffer 

The buffer that specifies the actions that VAXTPU should take whenever 
it processes a focus-in event. 

learnjsequence 

The learn sequence that specifies the actions that VAXTPU should take 
whenever it processes a focus-in event. 

program 

The program that specifies the actions that VAXTPU should take whenever 
it processes a focus-in event. 

range 

The range that specifies the actions that VAXTPU should take whenever it 
processes a focus-in event. 

string 

The string that specifies the actions that VAXTPU should take whenever 
it processes a focus-in event. 

NONE 

A keyword directing VAXTPU to delete the input focus grab routine. If you 
specify this ke 3 rword or do not specify the parameter at all, the appHcation 
is not notified when input focus is received. 

DESCRIPTION 

For more information about VAXTPU input focus support, see Chapter 4. 
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SIGNALED 

ERRORS 


EXAMPLE 

SET (INPUT FOCUS 


TPU$_BADKEY 

WARNING 

You specified an invalid keyword 
as a parameter. 

TPU$JNVPARAM 

ERROR 

One of the parameters was 
specified with data of the wrong 
type. 

TPU$_NORETURNVALUE 

ERROR 

SET (INPUT_FOCUS_GRAB) 
cannot return a value. 

TPU$_REQUIRESDECW 

ERROR 

You can use the SET (INPUT. 
FOCUS.GRAB) built-in only if you 
are using DECwindows VAXTPU. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to 
the SET (INPUT_FOCUS_GRAB) 
built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the SET (INPUT_FOCUS_GRAB) 
built-in. 


GRAB, SCREEN, "user_grab_focus"); 

This statement designates the procedure user_grab_focus as an input 
focus grab routine. For another example of code using the SET (INPUT_ 
FOCUS_GRAB) built-in, see Example 7-1. 
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SET (INPUT_FOCUS_UNGRAB) 



Specifies the program or learn sequence that VAXTPU should execute 
whenever it processes a focus-out event. 

FORMAT 

' buffer 

learnjsequence 

SET (INPUT FOCUS UNGRAB, SCREEN 1 J P''°9i'am 

range 

string 

1 NONE J 

PARAMETERS 

INPUT_FOCUS_UNGRAB 

A keyword directing VAXTPU to set an attribute related to an input focus 
ungrab routine. 

SCREEN 

A keyword used for compatibility with future versions of VAXTPU. 

buffer 

The buffer that specifies the actions that VAXTPU should take whenever 
it processes a focus-out event. 

Iearn_sequence 

The learn sequence that specifies the actions that VAXTPU should take 
whenever it processes a focus-out event. 

program 

The program that specifies the actions that VAXTPU should take whenever 
it processes a focus-out event. 

range 

The range that specifies the actions that VAXTPU should take whenever it 
processes a focus-out event. 

string 

The string that specifies the actions that VAXTPU should take whenever 
it processes a focus-out event. 

NONE 

A keyword directing VAXTPU to delete the input focus ungrab routine. 

If you specify this keyword or do not specify the parameter at aU, the 
application is not notified when input focus is lost. 

DESCRIPTION 

For more information about VAXTPU input focus support, see Chapter 4. 
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ERRORS 

TPU$_BADKEY 

WARNING 

You specified an invalid keyword 
as a parameter. 


TPU$JNVPARAM 

ERROR 

One of the parameters was 
specified with data of the wrong 
type. 


TPU$_NORETURNVALUE 

ERROR 

SET (INPUT_FOCUS_UNGRAB) 
cannot return a value. 


TPU$_REQUIRESDECW 

ERROR 

You can use the SET (INPUT_ 
FOCUS_UNGRAB) built-in only 
if you are using DECwindows 
VAXTPU. 


TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
SET (INPUT_FOCUS_UNGRAB) 
built-in. 


TPU$_TOOMANY 

ERROR 

Too many arguments passed 
to the SET (INPUT FOCUS 
UNGRAB) built-in. 


EXAMPLE 

SET (INPUT_FOCUS_UNGRAB, SCREEN, "user_ungrab_focus"); 

This statement designates the procedure user_ungrab_focus as an input 
focus ungrab routine. For another example of code using the SET (INPUT_ 
FOCUS_UNGRAB) built-in, see Example 7-1. 
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SET (INSERT) 


FORMAT 

SET (INSERT, buffer) 

PARAMETERS 

iNSERT 

A keyword specifying the mode of entering text. INSERT means that 
characters are added to the buffer immediately before the editing point. 
See also the description of the built-in procedure SET (OVERSTRIKE). 

The default mode for text entry is insert. 

buffer 

The buffer whose mode of text entry you want to set. 

SIGNALED 

ERRORS 

TPU$_TOOFEW ERROR SET (INSERT) requires two 

parameters. 

TPU$_TOOMANY ERROR You specified more than two 

parameters. 

TPU$JNVPARAM ERROR One or more of the specified 

parameters have the wrong type. 


EXAMPLE 

SET (INSERT, my_buffer) 

This statement causes the characters that you add to the buffer to be 
added immediately before the editing point. 
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SET (JOURNALING) 



Turns buffer change journaling on or off, sets the journaling frequency, and 
specifies a journal file name. 

FORMATS 

SET (JOURNALING, buffer ^ Y integer [,file_name_string ]) 

or 

SET (JOURNALING, integer) 

PARAMETERS 

JOURNALING 

A keyword indicating that the SET built-in is being used to enable or 
disable buffer change journaling, or set the frequency of journaling. 

buffer 

The buffer for which you want to enable or disable buffer change 
journaling. 

ON 

A ke 3 nvord turning on buffer change journaling. 

OFF 

A ke 3 rword turning off buffer change journaling. 

file_name_string 

The string naming the file you want to use as the buffer’s journal file. 

If the file does not exist, VAXTPU automatically creates it. You cannot 
specify this parameter if you have specified the ke 5 rword OFF for the third 
parameter. If you do not specify any file name when you turn journaling 
on, VAXTPU creates a journal file for you and names the file using the 
default naming algorithm. For more information on this algorithm, see 
Section 1.7.1. 

integer 

The integer that you specify that determines how frequently records are 
written to the journal file. The value of this integer must be between 1 
and 10. 

DESCRIPTION 

Journaling can be turned on only if the buffer is safe for journaling. For 
a buffer to be safe for journaling, it must either be empty, have never 
been modified, or be unmodified since the last time it was written to a 
file. (Whether the buffer has been modified is not the same as whether the 
buffer is marked as modified. The modified flag can be set or cleared by 
the application or by the user.) 
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SET (JOURNALING) 


Once a buffer that is being journaled is written to a file, the journal file 
is closed and deleted, and a new journal file is started that references the 
newly created file. Similarly, reading a file into an empty buffer does not 
copy the file into the journal—^it simply inserts a reference to the file in 
the journal. Note that this behavior must be taken into account when 
you perform operations that use temporary files. For example, writing a 
buffer to a temporary file (which is modified by an external program), then 
erasing the buffer and re-reading a (modified) temporary file will point the 
journal file at the temporary file. If you then delete the temporary file, the 
buffer will be unrecoverable. 

A journal file name can be supplied only if journaling is being turned on. 

If a journal file name is supplied, VAXTPU creates a journal file using 
the name you specified. If this parameter is omitted, VAXTPU creates a 
journal file name based on the buffer’s name using the algorithm outlined 
in Section 1.7.1. 

If journaling is being turned off for the specified buffer, VAXTPU closes the 
journal file but does not delete it. 

VAXTPU signals a warning or error if any of the following conditions 
apply: 

• Journaling is being turned on and one or more of the following is also 
true: 

— The specified buffer is not safe for journaling. 

— The specified buffer is already being journaled. 

— An RMS error was returned when VAXTPU tried to create the 
journal file. 

• Journaling is being turned off and a journal file name is specified in 
the built-in call. 

Caution: Journal files contain a record of all information being edited. 

Therefore, when editing files containing secure or confidential 
data, be sure to keep the journal files secure as well. 

The integer parameter specifies the journaling frequency. VAXTPU 
provides a 500-b3de buffer for journaling keystrokes. If journaling is 
enabled, a write to the journal file occurs when the buffer is full. This 
built-in procedure lets you determine the frequency with which records are 
written to the journal file; the lower the integer you specify, the more often 
journal records are written to disk. 

A value of 1 causes a record to be written for approximately every 10 keys 
pressed. A value of 10 causes a record to be written for approximately 
every 125 keys. If you are entering only text (rather than procedures 
that are bound to keys), the number of keystrokes included in a record is 
greater—^for a value of 1, a record is written for approximately every 30 
to 35 keystrokes; for a value of 10, a record is written for approximately 
every 400 keystrokes. 
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SET (JOURNALING) 


SIGNALED 

ERRORS 

TPU$_MINVALUE 

WARNING 

Argument is less than minimum 
allowed. 


TPU$_MAXVALUE 

WARNING 

Argument is greater than 
maximum allowed. 


TPU$_TOOMANY 

ERROR 

You specified too many 
parameters. 


TPU$_TOOFEW 

ERROR 

You specified too few parameters. 


TPU$JNVPARAM 

ERROR 

You specified a parameter with the 
wrong data type. 


TPU$_BADKEY 

ERROR 

You specified an invalid keyword. 


TPU$_JRNLOPEN 

ERROR 

A journal file for this buffer is 
already open. 


EXAMPLES 

0 SET (JOURNALING, CURRENT_BUFFER, ON, "diskl:[jones]journal.jnl"); 

This statement turns on buffer change journaling for the current buffer 
and directs VAXTPU to use the file JOURNAL. JNL in the directory 
[JONES] as the journal file. 

g SET (JOURNALING, 1) 

This statement causes a record to be written from the buffer to a journal 
file at intervals of approximately 10 user keystrokes. If all or most of the 
keys pressed have procedures bound to them, VAXTPU may write out 
the contents of the buffer after fewer than 10 keystrokes. The joiumaling 
interval shown in this statement is the shortest that you can specify. 
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SET (KEYSTROKE_RECOVERY) 



Turns keystroke journal recovery on or off. 

FORMAT 

SET (KEYSTROKE_RECOVERY }; 

PARAMETERS 

KEYSTROKE_RECOVERY 

A keyword directing VAXTPU to enable or disable keystroke recovery, 
depending on whether /RECOVER or /NORECOVER was specified on the 
command line. 

ON 

A keyword enabhng keystroke recovery. (This has the same effect as 
specifying the /RECOVER qualifier.) 

OFF 

A keyword disabling keystroke recovery. (This has the same effect as 
specifying the /NORECOVER qualifier.) 

DESCRIPTION 

If the /RECOVER qualifier is specified on the DCL command line, VAXTPU 
checks whether the apphcation calls the JOURNAL_OPEN built-in to open 
a keystroke journal file. If the application does not call the JOURNAL_ 
OPEN built-in, by default VAXTPU signals an error when the apphcation 
starts accepting keyboard input. 

In some circumstances, you may want your apphcation to accept the 
/RECOVER qualifier without error, even though the apphcation does not 
cah the JOURNAL_OPEN built-in. For example, if your apphcation uses 
only buffer-change journaling, the /RECOVER qualifier can be used when 
VAXTPU is invoked, but the JOURNAL_OPEN built-in is not used. 

To disable the error caused by the lack of a call to JOURNAL-OPEN and 
concurrently to prevent VAXTPU from performing keystroke recovery 
(even if /RECOVER is specified and you use JOURNAL OPEN) use SET 
(KEYSTROKE.RECOVERY, OFF). Conversely, to direct VAXTPU to 
perform keystroke recovery (even if /NORECOVER is specified and you 
use JOURNAL_OPEN), use SET (KEYSTROKE_RECOVERY, ON). 

Note that SET (KEYSTROKE_RECOVERY) signals an error if the 
apphcation code or the user calls the built-in after VAXTPU has started 
accepting keyboard input. 

To determine whether a recovery using a keystroke journal file is currently 
in progress, use GETJNFO (SYSTEM, "recover"). This GETJNFO cah 
returns FALSE (0) if no keystroke recovery is currently in progress, and 
returns TRUE (1) if a keystroke recovery is currently in progress. Note 
that SET (KEYSTROKE_RECOVERY) C 2 m determine the value returned 
by GETJNFO (SYSTEM, "recover") but caimot affect the value returned 
by GETJNFO (COMMAND_LINE, "recover"). GETJNFO (COMMAND. 
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LINE, "recover") returns a value indicating whether /RECOVER was 
specified when VAXTPU was invoked. 


SIGNALED 

ERRORS 

TPU$_JNLNOTOPEN 

ERROR 

No keystroke journal file is open 
from which to recover. 


TPU$_RECJNLOPEN 

ERROR 

A keystroke journal file is already 
open. 


TPU$_TOOFEW 

ERROR 

You specified too few parameters. 


TPU$_TOOMANY 

ERROR 

You specified too many 
parameters. 


TPU$JNVPARAM 

ERROR 

You specified a parameter with the 
wrong data type. 


TPU$_BADKEY 

ERROR 

You specified an invalid keyword. 


EXAMPLE 

SET (KEYSTROKE_RECOVERY, ON) 

This statement directs VAXTPU to do keystroke journal recovery even if 
/NORECOVER was specified on the command line. 
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SET (KEY_MAP_LIST) 


FORMAT 

SET ^/CEV'_/VMP_L/S7; sfnngf 1 

PARAMETERS 

KEY_MAP_UST 

The key map list that you bind to a buffer or window. 

The default key map list is TPU$KEY_MAP_LIST. 

String 

A quoted string, or a variable name representing a string constant, that 
specifies the key map list that you bind to a buffer or window. 

buffer 

Buffer to which you bind the specified key map list. The default is the 
buffer to which you are positioned. 

window 

The window with which you want to associate the key map list. 

The key map list manipulated by SET (KEY_MAP_LIST) is used only to 
process mouse events in the specified window. Keystrokes are processed 
using the key map list associated with the buffer. 

DESCRIPTION 

The SET (KEY_MAP_LIST) built-in procedure binds a specified key map 
list to a buffer or window. If the buffer or window is not specified, the 
default is to bind the key map list to the current buffer. A buffer or 
window can be associated with only one key map list at a time. A key map 
list can be associated with many buffers or windows simultaneously. 

SIGNALED 

ERRORS 

TPU$_NOKEYMAPLIST WARNING Attempt to access an undefined 

key map list. 

TPU$ TOOFEW ERROR Too few arguments passed to the 

SET (KEY_MAP_LIST) built-in. 

TPU$_TOOMANY ERROR Too many arguments passed to 

the SET (KEY_MAP_LIST) built-in. 

TPU$_NOCURRENTBUF ERROR You are not positioned in a buffer. 

TPU$_INVPARAM ERROR Wrong type of data sent to the 

SET (KEY_MAP_LIST) built-in. 


7-410 









VAXTPU Built-In Procedures 

SET (KEY_MAP_LIST) 


EXAMPLE 

SET (KE Y_MAP_LI ST, " t pu $_key_map_l i s t") 

This statement binds the key map list called TPU$_KEY_]V[AP__LIST to 
the current buffer. 

PROCEDURE user_scratch__winciow 

LOCAL scratch_window, 
scratch_buffer, 
scratch_map, 
scratch_list; 

scratch_window := CREATE__WINDOW (20, 3, ON) ; 
scratch_buffer := CREATE_BUFFER ("test”, "junk.txt"); 
scratch_map := CREATE__KEY_MAP ("user_scratch_map"); 

DEFINE_KEY (eve$$kt_return + "sample_Ml_DRAG", MIDRAG, "mouse_button_l", 

"use r_s c rat ch_map"); 

scratch_list ;= CREATE_KEY_MAP_LIST ("user_scratch_list", "user_scratch__map", 

eve$x_mouse_keys); 

SET (KEY_MAP_LIST, "user_scratch_list", scratch_window); 

MAP (scratch_window, scratch_buffer); 

ENDPROCEDURE; 

This procedure creates a small "scratch pad" window and maps it to 
a scratch buffer called junkl.txt. The procedure defines a key map 
list consisting of a user-defined key map redefining MIDRAG plus the 
standard EVE mouse key map. By setting the scratch window’s key map 
list to be user_scratch_list, the procedure invokes sample_ml_drag when 
the user drags the mouse in the scratch window. 
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SET (LEFT_MARGIN) 


FORMAT 

SET (LEFT_MARGIN. buffer, integer) 

PARAMETERS 

LEFT_MARGIN 

The left margin of a buffer. 

buffer 

The buffer in which the left margin is being set. 

integer 

The column at which the left margin is set. 

DESCRIPTION 

The SET (LEFT_MARGIN) built-in procedure allows you to change only 
the left margin of a buffer. 

Newly created buffers receive a left margin of 1 (that is, the margin is 
set in column 1) if a template buffer is not specified in the call to the 
CREATE_BUFFER built-in procedure. If a template buffer is used, that 
buffer sets the left margin for all newly created buffers. 

Use SET (LEFT_MARGIN) to override the default left margin. 

The buffer margin settings are independent of the terminal width or 
window width settings. 

The buUt-in procedure FILL uses these margin settings when it fills the 
text of a buffer. 

When VAXTPU creates a new line, the line obtains its left margin value 
from the left margin of the current buffer setting. However, changing the 
left margin setting for the buffer does not change the left margin for any 
existing lines. 

The value of the left margin must be at least 1 and less than the right 
margin value. 

If you want to use the margin settings of an existing buffer in a user- 
written procedure, GET_INFO (buffer, “left_margin”) and GETJNFO 
(buffer, “right_margin”) return the values of the margin settings in the 
specified buffer. 

SIGNALED 

ERRORS 

TPU$_TOOFEW ERROR The SET (LEFT_MARGIN) built-in 

requires three parameters. 

TPU$_TOOMANY ERROR You specified more than three 

parameters. 
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TPU$JNVPARAM 

TPU$_BADMARGINS 


ERROR One or more of the specified 

parameters have the wrong type. 

WARNING The left margin setting must be 
less than the right; both must be 
greater than zero. 


EXAMPLES 

Q SET (LEFT_MARGIN, my_buffer, 1) 


This statement causes the left margin of the buffer represented by the 
variable myjbuffer to be changed. The left margin of the buffer is set to 1. 
The right margin is unchanged. 

g SET (LEFT_MARGIN, CURRENT_BUFFER, 10) 


This statement causes the left margin of the current buffer to be changed 
to 10. As above, the right margin is unchanged. 
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SET (LEFT_MARGIN_ACTION) 


FORMAT 


SET (LEFT_MARGIN_ACTION, bufferl 


, buffer2 

, learnjsequence 
, program > 

, range 
, string 


) 


PARAMETERS LEFT_MARGIN_ACTION 

Refers to the action taken when the user presses a self-inserting key while 
the cursor is to the left of a line’s left margin. A self-inserting key is one 
that is associated with a printable character. 

bufferl 

The buffer in which the left margin action routine is being set. 

buffer2 

A buffer containing the VAXTPU statements to be executed when the user 
presses a self-inserting key while the cursor is to the left of a buffer’s left 
margin. 

Iearn_sequence 

A learn sequence that is to be replayed when the user presses a self- 
inserting key while the cursor is to the left of a buffer’s left margin. 

program 

A program that is to be executed when the user presses a self-inserting 
key while the cursor is to the left of a buffer’s left margin. 

range 

A range that contains VAXTPU statements that are to be executed when 
the user presses a self-inserting key while the cursor is to the left of a 
buffer’s left margin. 

String 

A string that contains VAXTPU statements that are to be executed when 
the user presses a self-inserting key while the cursor is to the left of a 
buffer’s left margin. 


DESCRIPTION The SET (LEFT_MARGIN_ACTION) built-in procedure allows you to 

specify an action to be taken when the user attempts to insert text to the 
left of the left margin of a line. If the third parameter is not specified, the 
left margin action routine is deleted. If no left margin action routine has 
been specified, the text is simply inserted at the current position before 
any necessary padding spaces, and the left margin of the line becomes the 
current position. 
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Newly created buffers do not receive a left margin action routine if a 
template buffer is not specified on the call to the CREATE_BUFFER 
built-in procedure. If a template buffer is specified, the left margin action 
routine of the template buffer is used. 

The left margin action routine only affects text entered from the keyboard 
or a learn sequence. Inserting text into a buffer to the left of the left 
margin using the COPY_TEXT or MOVE_TEXT built-in procedure does 


not trigger the left margin action routine. 

SIGNALED 

ERRORS 

TPU$_TOOFEW 

ERROR 

The SET (LEFT_MARGIN_ 
ACTION) built-in requires at least 
two parameters. 


TPU$_TOOMANY 

ERROR 

You specified more than three 
parameters. 


TPU$_INVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 


TPU$_COMPILEFAIL 

ERROR 

Compilation aborted because of 
syntax errors. 

EXAMPLES 




Q SET (LEFT_MARGIN 

_ACTION, CURRENT_BUFFER, 

" pu s h__t o_l e f t _ 

__margin") 


This statement causes the procedure PUSH_TO_LEFT_MARGIN to be 
executed when the user attempts to type a character to the left of the left 
margin of the current line. A typical left margin action routine moves 
the editing point to the left margin and inserts an appropriate number of 
spaces starting at the left margin. 

SET (LEFT_MARGIN_ACTION, CURRENT^BUFFER) 

This statement deletes any left margin action routine that may be defined 
for the current buffer. When there is no user-defined left margin action 
routine, if the user types a character to the left of the current line's left 
margin, the text is inserted with spaces padding the text to the old left 
margin. The leftmost character on the line establishes the line’s new left 
margin. 
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SET (UNE_NUMBER) 


FORMAT 

SET (LINE_NUMBER, { }; 

PARAMETERS 

UNE_NUMBER 

Refers to the VAXTPU display of the procedure and line number at which 
an error occurred. 

ON 

Turns on display of the line number and procedure at which an error 
occurred. 

OFF 

Turns off display of the line number and procedure at which an error 
occurred. 

DESCRIPTION 

Line numbers are useful for programmers debugging VAXTPU programs, 
but they do not have much meaning to users who do not have the source 
code available to them. 

After a compilation, the line numbers displayed for procedures are relative 
to the beginning of the procedure. For VAXTPU statements compiled 
outside a procedure, the hne numbers displayed are relative to the 
beginning of the buffer, range, or string being compiled. If there are no 
procedure declarations before the executable statements, line numbering 
starts at the beginning of the buffer or range that is being compiled. For 
strings, the line number is always 1. 

Line numbers may be changed when you use the SAVE built-in to write a 
section file. If you specify the parameter NO_PROCEDURE_NAMES, the 
line numbers displayed are relative to the beginning of the buffer or range 
that was compiled, not relative to the beginning of a procedure. 

The default setting for LINE_NUMBER depends on whether a section file 
was loaded by VAXTPU. If a section file was loaded, the default is OFF. If 
a section file was not loaded, the default is ON. 

Note that SET (LINE_NUMBER) is related to SET (TRACEBACK). SET 
(TRACEBACK, ON) turns on both traceback and line numbers. SET 
(LINE_NUMBER, OFF) turns off both traceback and line numbers. It is 
also possible to set traceback off and line numbers on. 


7-416 















VAXTPU Built-In Procedures 

SET (LINE_NUMBER) 


SIGNALED 

ERRORS 


TPU$_TOOFEW 

ERROR 

The SET (LINE_NUMBER) built-in 
requires two parameters. 

TPU$_TOOMANY 

ERROR 

You specified more than two 
parameters. 

TPUSJNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 

TPU$_BADKEY 

ERROR 

Only the keywords ON and OFF 
are allowed. 


EXAMPLE 

PROCEDURE line__number__example 
SET (LINE_NUMBER, ON) ; 

SET (LINE_NUMBER, BELL); 
ENDPROCEDURE; 


This procedure displays the line number at which the error occurred. 
Executing this procedure displays the following in the message buffer: 

BELL is an invalid keyword 
At line 4 
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SET (MAPPED_WHEN_MANAGED) 



Controls whether a widget instance is mapped to the screen when it is 
managed. 

FORMAT 

SET (MAPPED_WHEN_MANAGED,widget, [ }; 

PARAMETERS 

MAPPED_ WHEN_MANAGED 

A keyword indicating that SET is being used to control whether the 
specified widget instance should become visible when it is managed. 

widget 

The widget instance whose mapped status you want to set. 

ON 

A keyword directing VAXTPU to make the specified widget visible when it 
is managed. This is the default value. 

OFF 

A keyword directing VAXTPU not to make the specified widget visible 
when it is managed. 

DESCRIPTION 

For more information on managing widgets, see the VMS DECwindows 
Guide to Application Programming and the VMS DECwindows Toolkit 
Routines Reference Manual. 

SIGNALED 

ERRORS 

TPU$JNVPARAM ERROR One of the parameters was 

specified with data of the wrong 
type. 

TPU$_NORETURNVALUE ERROR Built-in does not return a value. 

TPU$_REQUIRESDECW ERROR Requires the VAXTPU 

DECwindows screen updater. 

TPU$_TOOFEW ERROR You specified too few parameters. 

TPU$_TOOMANY ERROR You specified too many 

parameters. 


EXAMPLE 

SET (MAPPED_WHEN_MANAGED, exainple_widget, OFF); 

This statement directs VAXTPU to make the widget contained in example, 
widget invisible when the widget is managed. 
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SET (MARGINS) 


FORMAT 

SET (MARGINS, buffer, integerl, integer2) 

PARAMETERS 

MARGINS 

A keyword indicating that SET is to determine the left and right margins 
of a buffer. 

The default left margin is 1 and the default right margin is 80. 

buffer 

The buffer in which the margins are being set. 

integerl 

The column at which the left margin is set. 

integer2 

The column at which the right margin is set. 

DESCRIPTION 

The SET (MARGINS) built-in procedure allows you to change the left and 
right margins of a buffer. The default margins for a buffer are set to 1 for 
the left margin and 80 for the right margin when you use the CREATE. 
BUFFER built-in. The built-in procedure FILL uses these margin settings 
when it fills the text of a buffer. 

This built-in procedure controls the buffer margin settings even if the 
terminal width or window width is set to something else. 

The value of the left margin must be at least 1 and less than the right 
margin value. The value of the right margin must be less than the 
maximum record size for the buffer. You can use the built-in procedure 
GET.INFO (buffer, “record.size”) to find out the maximum record size of a 
buffer. 

If you want to use the margin settings of an existing buffer in a user- 
written procedure, the statements GETJNFO (buffer, “left.margin”) 
and GETJNFO (buffer, “right.margin”) return the values of the margin 
settings. 

SIGNALED 

ERRORS 

TPU$_TOOFEW ERROR The SET (MARGINS) built-in 

requires five parameters. 

TPU$_TOOMANY ERROR You specified more than four 

parameters. 

TPUSJNVPARAM ERROR One or more of the specified 

parameters have the wrong type. 
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TPU$_BADMARGINS WARNING Left margin must be smaller than 

right; both must be greater than 
zero. 


EXAMPLES 

D SET (MARGINS, mY_buffer, 1, 132) 

This statement causes the margins of the buffer represented by the 
variable myjbuffer to be changed. The left margin of the buffer is set to 1 
and the right margin is set to 132. 

g SET (MARGINS, CURRENT_BUFFER, 10, 70) 

This statement causes the margins of the current buffer to be changed to 
left margin 10 and right margin 70. 
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SET (MAX_LINES) 


FORMAT 

SET (MAX_LINES, buffer, integer) 

PARAMETERS 

MAX_UNES 

The maximum number of lines a buffer can contain. 

buffer 

The buffer for which you are setting the maximum number of lines. 

integer 

The maximum number of lines for the buffer. The valid values are 0, 2, or 
an integer greater than 2. The maximum value depends on the memory 
capacity of your system. 

The default maximum number of lines is 0 (in other words, this feature is 
turned off). 

DESCRIPTION 

If you exceed the maximum number of lines for a buffer, VAXTPU deletes 
lines from the beginning of the buffer to make room for any lines that 
exceed the maximum. 

Note that SET (MAX_LINES) does not consider the end-of-buffer text to 
be a record. For example, if you set the maximum number of lines to be 
1000, the buffer can contain 1000 records plus the end-of-buffer text. 

If you specify a value of 0 for integer, this feature is turned off and 
VAXTPU does not check for the maximum number of lines. 

SIGNALED 

ERRORS 

TPU$_MIN\/ALUE WARNING Argument less than minimum 

allowed. 

TPU$_MAXVALUE WARNING Argument greater than maximum 

allowed. 

TPU$JNVPARAM ERROR One or more of the specified 

parameters have the wrong type. 

TPU$_TOOMANY ERROR SET {MAX_LINES) accepts only 

three parameters. 

TPU$_TOOFEW ERROR SET (MAX_LINES) requires three 

parameters. 


EXAMPLE 

SET (MAX_LINES, message_buffer, 20) 

This statement causes the maximum number of lines for the message 
buffer to be 20. Only the most recent lines of messages are kept. 
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SET (MENU_POSITION) 



Sets menu positioning for one or more pop-up widgets. 

FORMAT 

{ } ■= SET (MENUJPOSITION, mouse_down_button, 

( array2 \ 

^ NONE J; 

[ widget J 

PARAMETERS 

MENU_POSmON 

A keyword indicating that the SET built-in is being used to set the menu 
position of a pop-up widget or widgets. 

mousejdownjbutton 

This keyword (MIDOWN, M2DOWN, M3DOWN, M4DOWN, or M5DOWN) 
indicates the mouse button associated with the pop-up menus. 

array2 

An integer-indexed array of pop-up menu widgets to be set for automatic 
menu positioning. 

NONE 

This ke^ord requests that VAXTPU stop automatic positioning of pop-up 
menu widgets for the specified mouse button. 

widget 

The pop-up menu widget to be set for automatic menu positioning. 

return values 

arrayl 

An integer-indexed array of all pop-up menu widgets that were set for 
automatic positioning for the specified mouse button prior to this built-in 
call. 

NONE 

A keyword indicating that no pop-up menu widgets were set for the 
specified mouse button prior to this built-in rail 

DESCRIPTION 

When the specified mouse button is pressed and the application manages a 
pop-up widget, VAXTPU positions the pop-up widget so that the last menu 
item chosen is at the mouse pointer. If no menu item has been chosen, 
VAXTPU positions the pop-up widget so that the mouse pointer is at the 
upper left comer of the widget. 
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SET (MENU_POSITION) 


SIGNALED 

ERRORS 

TPU$JNVPARAM 

ERROR 

One of the parameters was 
specified with data of the wrong 
type. 


TPU$_REQUIRESDECW 

ERROR 

Requires the VAXTPU 
DECwindows screen updater. 


TPU$_TOOFEW 

ERROR 

You specified too few parameters. 


TPU$_TOOMANY 

ERROR 

You specified too many 
parameters. 


TPU$_BADKEY 

WARNING 

You specified an invaiid keyword. 


TPU$_NEEDTOASSIGN 

ERROR 

Built-in must return a value. 


TPU$_EXTRANEOUSARGS 

ERROR 

The array of widgets parameter 
had a non-widget element. 


TPU$_REQARGSMISSING 

ERROR 

The array of widgets parameter 
was empty. 
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SET (MESSAGE_ACTION_LEVEL) 


SET (l\/IESSAGE_ACTION_LEVEL) 


FORMAT 


SET (MESSAGE_ACTION_LEVEL, | L 


PARAMETERS MESSAGE_ACT10N_LEVEL 

A keyword indicating that SET is to determine the severity level at which 
VAXTPU sounds the terminal bell or hig hlights a message. 

integer 

A value between 0 and 3 specifying the severity level at which VAXTPU 
is to take the action you designate. The default value is 2. The severity 
levels and correspon^ng values, in ascending order of severity, are as 
follows: 

1 Success 

3 Informational 

0 Warning 

2 Error 

VAXTPU performs the action you specify on all completion messages at 
the severity level you designate and on all messages of greater severity. 

keyword 

The keyword associated with a VAXTPU completion message. VAXTPU 
uses the keyword to determine the severity level of the associated 
completion message and performs the action you specify on all completion 
messages of that severity level or greater. 


DESCRIPTION To set the action that is taken when VAXTPU returns a completion status 

of the specified severity, use the SET (MESSAGE_ACTION_TYPE) built-in. 

The action you specify using SET (MESSAGE_ACTION_TYPE) is taken 
for all completion messages of the specified severity or greater severity. 


SIGNALED 

ERRORS 

TPU$_TOOFEW 

ERROR 

SET (MESSAGE_ACTION_ 
LEVEL) requires two parameters. 


TPU$_TOOMANY 

ERROR 

You specified more than two 
parameters. 


TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 


TPU$_BADKEY 

ERROR 

You specified an invalid keyword. 


TPU$JLLSEVERITY 

WARNING 

Illegal severity specified; VAXTPU 
used the severity "error." 
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SET (MESSAGE_ACTION_LEVEL) 



EXAMPLES 

Q SET 
SET 

g SET 
SET 



(MESSAGE_ACTION_TYPE, REVERSE); 

(MESSAGE_ACTION_LEVEL, 3); 

These statements direct VAXTPU to display informational, warning, and 
error messages in reverse video for 1/2 second, then in ordinary video. 

(MESSAGE_ACTION_TYPE, BELL); 

(MESSAGE_ACTION_LEVEL, TPU$_SUCCESS); 

These statements direct VAXTPU to ring the terminal’s bell whenever 
a completion status occurs with a severity equal to or greater than the 
severity of TPU$_SUCCESS. 
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SET (MESSAGE_ACTION_TYPE) 


SET (MESSAGE_ACTION_TYPE) 


FORMAT 


f NONE 

SET (MESSAGE_ACTION_TYPE, ^ BELL 

I REVERSE 


PARAMETERS MESSAGE_ACTION_TYPE 

A keyword indicating the action to be taken when VAXTPU generates a 
completion status of the severity you specify. 

NONE 

A keyword directing VAXTPU to take no action. This is the default. 

BELL 

A keyword directing VAXTPU to ring the terminal’s bell when a completion 
status of the specified severity is returned. 

REVERSE 

A ke3rword directing VAXTPU to display the completion status in reverse 
video for 1/2 second, then display the status in ordinary video. 


DESCRIPTION To set the severity at which the action is taken, use the SET (MESSAGE. 

ACTION_LEVEL) built-in. The action you specify using SET (MESSAGE 
ACTION_TYPE) is taken for all completion messages of the specified 
severity or greater severity. 


SIGNALED 

ERRORS 

TPU$_TOOFEW 

ERROR 

SET (MESSAGE_ACTION_TYPE) 
requires two parameters. 


TPU$_TOOMANY 

ERROR 

You specified more than two 
parameters. 


TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 


TPU$_BADKEY 

ERROR 

You specified an invalid keyword. 


EXAMPLE 

SET (MESSAGE_ACTION_TYPE, REVERSE); 

SET (MESSAGE_ACTION_LEVEL, 3); 

These statements direct VAXTPU to display informational, war ning s and 
error messages in reverse video for 1/2 second, then in ordinary video. 
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SET (MESSAGE_FLAGS) 


SET (MESSAGE_FLAGS) 

FORMAT 

SET (MESSAGE_FLAGS, integer) 

PARAMETERS 

MESSAGE_FLAGS 

The message flags in the $PUTMSG system service. 


integer 

The value specified for the $PUTMSG message codes. Table 7—11 lists the 
message codes. 


DESCRIPTION The following table shows the message codes for $PUTMSG: 


Table 7-11 

Message Codes for $PUTMSG System Service 

Bit 

Value 

Meaning 

0 

1 

Include text of message. 


0 

Do not include text of message. 

1 

1 

Include message identifier. 


0 

Do not include message identifier. 

2 

1 

Include severity level Indicator. 


0 

Do not include severity level indicator. 

3 

1 

Include facility name. 


0 

Do not include facility name. 


If you do not set a value for the message flags, the default message flags 
for your process are used. Setting the message flags to 0 does not turn 
off the message text; it causes VAXTPU to use the default message flags 
for your process. In addition to setting the message flags from within 
VAXTPU, you can set them at the DCL level with the command SET 
MESSAGE. The DCL command SET MESSAGE is the only way you can 
turn off all message text. See the VMS DCL Dictionary for information on 
the DCL command SET MESSAGE. 

Table 7-12 shows the predefined constants available for use with SET 
(MESSAGE.FLAGS). 


Table 7-12 Message Flag Values 


Bit 

Constant 

Meaning 

0 

TPU$K_MESSAGE_TEXT 

Include text of message. 

1 

TPU$K_MESSAGEJD 

Include message identifier. 

2 

TPU$K_MESSAGE_SEVERITY 

Inciude severity ievel indicator. 

3 

TPU$K_MESSAGE_FACILITY 

Inciude facility name. 
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SET (MESSAGE_FLAGS) 


SIGNALED 

ERRORS 

TPU$_FLAGTRUNC 

WARNING 

Message flag values must be less 
than or equal to 15. 


TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 


TPU$_TOOFEW 

ERROR 

SET (MESSAGE^FLAGS) requires 
at least two parameters. 


TPU$_TOOMANY 

ERROR 

SET (MESSAGE_FLAGS) accepts 
no more than two parameters. 


EXAMPLES 

D SET (MESSAGE_FLAGS, 2) 

This statement causes the message identifier to be the only item included 
in VAXTPU messages. The integer 2 sets bit 1. 

§ SET (MESSAGE_FLAGS, 5) 

This statement causes the message text and the severity level indicator to 
be included in VAXTPU messages. The integer 5 is a bit-encoded integer 
setting both bit 2 and bit 0 to 1. 

S SET (MESSAGE_FLAGS, TPU$K_MESSAGE_SEVERITY); 

MESSAGE (TPU$_TOOFEW); 


In this code fragment, the SET (MESSAGE_FLAGS) statement directs 
VAXTPU to include only the message severity level in messages identified 
by keywords or integers. Since TPU$_TOOFEW is an error-level message, 
the MESSAGE statement above causes VAXTPU to display "%E’' in the 
message buffer. VAXTPU does not display the text associated with the 
keyword TPU$_TOOFEW because the statement does not contain an 
integer or constant directing VAXTPU to display the text. For more 
information on using constants to specify message format, see the 
description of the MESSAGE_TEXT built-in. 

Q SET (MESSAGE_FLAGS, TPU$K_MESSAGE_ID + TPU$K_MESSAGE_TEXT); 

MESSAGE (TPU$ TOOFEW); 


In this code fragment, the integer parameter to SET (MESSAGE_ 
FLAGS) is specified as two constants representing encoded bits. This 
message flag setting turns on the display of both message identifier 
and message text. Therefore, when the MESSAGE statement in this 
code fragment is compiled and executed, VAXTPU displays the words 
"%TOOFEW, Too few arguments" in the message buffer. 


7-428 








VAXTPU Built-In Procedures 

SET (MODIFIABLE) 


SET (MODIFIABLE) 


FORMAT 

SET (MODIFIABLE, buffer, { }; 

PARAMETERS 

MODIFIABLE 

The ability to modify a buffer. 

buffer 

The buffer that will either be unmodifiable or able to be edited. 

ON 

Makes the buffer modifiable. 

OFF 

Makes the buffer unmodifiable, allowing only deletion of the buffer and 
setting of marks and ranges. Any attempt to change the buffer will result 
in a warning message. 

DESCRIPTION 

When a buffer is not modifiable, any attempt to insert, delete, or otherwise 
modify the contents of the buffer results in a warning message. This only 
affects the text within the buffer. The buffer can still be deleted, and 
marks and ranges can still be created or deleted in the text within the 
buffer. 

Newly created buffers are modifiable by default if a template buffer was 
not used on the call to the CREATE_BUFFER procedure. The modifiability 
status is taken from the template buffer if one was specified. 

You cannot make the messages buffer unmodifiable. 

SIGNALED 

ERRORS 

TPU$_TOOFEW ERROR The SET (MODIFIABLE) built-in 

requires three parameters. 

TPU$_TOOMANY ERROR You specified more than three 

parameters. 

TPU$_iNVPARAM ERROR One or more of the specified 

parameters have the wrong type. 

TPU$_MSGBUFSET ERROR You cannot force the message 

buffer to be nonmodifiable. 

TPU$_BADKEY ERROR Oniy the ON and OFF keywords 

are vaiid. 
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SET (MODIFIABLE) 


EXAMPLE 

SET (MODIFIABLE, 


CURRENT_BUFFER, OFF) 

This statement makes the current buffer unmodifiable. Any attempt to 
change the buffer fails with a warning message. 
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SET (MODIFIED) 


SET (MODIFIED) 



Turns on or turns off the flag indicating that the specified buffer has been 
modified. 

FORMAT 

SET (MODIFIED, buffer, { 

PARAMETERS 

MODIFIED 

A keyword directing VAXTPU to turn on or tiam off the indicator 
designating a buffer as modified. 

buffer 

The buffer whose indicator you want to control. 

ON 

A keyword directing VAXTPU to mark a buffer as modified. 

OFF 

A ke 5 nvord directing VAXTPU to mark a buffer as unmodified. 

DESCRIPTION 

Use SET (MODIFIED) with caution. When you turn off the flag indicating 
that the buffer is modified, it is possible to exit from an application layered 
on VAXTPU without writing out the contents of a modified buffer. Be sure 
your extension or layered application h8m.dles this possibility. 

SIGNALED 

ERRORS 

TPU$_BADKEY WARNING You specified an invalid keyword 

as a parameter. 

TPU$JNVPARAM ERROR One of the parameters was 

specified with data of the wrong 
type. 

TPU$_NORETURNVALUE ERROR SET (MODIFIED) cannot return a 

value. 

TPU$ TOOFEW ERROR Too few arguments passed to the 

SET (MODIFIED) built-in. 

TPU$ TOOMANY ERROR Too many arguments passed to 

the SET (MODIFIED) built-in. 


EXAMPLE 

SET (MODIFIED, CURRENT_BUFFER, ON); 

This statement marks the current buffer as modified. 
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SET (MOUSE) 


SET (MOUSE) 

FORMAT 

Mot }j 

PARAMETERS 

MOUSE 

Indicates that you are using SET to enable or disable VAXTElTs mouse 
support. 


The default mouse setting depends on the terminal you are using. If the 
VAXTPU statement GET_INFO (SCREEN, "dec_crt2") returns true on 
your terminal, mouse support is turned on by default. Otherwise, mouse 
support is turned off by default. 


ON 

Causes VAXTPU to recognize mouse buttons when they are pressed, and 
allows you to bind programs or procedures to mouse buttons. Enables the 
LOCATE_MOUSE and POSITION (MOUSE) built-ins. 


OFF 

Disables VAXTPU mouse support. Pressing a mouse button when the 
mouse is set to OFF has no effect. 

DESCRIPTION 

Since VAXTPU mouse support disables the terminal emulator’s cut and 
paste feature in non-DECwindows VAXTPU, you must turn off VAXTPU 
mouse support to use the non-VAXTPU cut and paste capability while 
VAXTPU is running. 


The optional return value specifies whether VAXTPU mouse support was 
enabled or disabled before the current SET (MOUSE) statement was 
executed. This allows you to enable or disable mouse support and then 
reset the support to its previous setting without having to make a separate 
call. 


SIGNALED 

ERRORS 

TPU$_BADKEY 

WARNING 

The keyword must be either ON or 
OFF. 


TPU$_MOUSEINV 

WARNING 

You have tried to enable mouse 
support on an incompatible 
terminal. 


TPU$_TOOFEW 

ERROR 

SET (MOUSE) requires two 
parameters. 


TPU$_TOOMANY 

ERROR 

You specified more than two 
parameters. 


TPUSJNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 
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SET (MOUSE) 


EXAMPLE 

SET (MOUSE, OFF) 

This statement turns off mouse support. 
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SET (NO_WRITE) 


SET (NO_WRITE) 


FORMAT 


SET (NO_WRITE, buffer 


j , ON 
\,OFF 



PARAMETERS NO^WRITE 

Specifies that VAXTPU should not create an output file from the contents 
of a buffer after execution of a QUIT or EXIT statement even if the 
contents of the buffer have been modified. 

By default, a buffer is written out if it has been modified. 

buffer 

The buffer whose contents you do not want written out. 

ON 

Causes the buffer you name not to be written out. 

OFF 

Lets you change a buffer from the no-write state to the default state. By 
default, any modified buffers are written out after execution of a QUIT or 
EXIT statement. 


SIGNALED 


ERRORS 

TPU$_TOOFEW 

ERROR 

SET (NO_WRITE) requires three 
parameters. 


TPU$_TOOMANY 

ERROR 

You specified more than three 
parameters. 


TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 


TPU$_BADKEY 

ERROR 

You specified an invalid keyword. 


EXAMPLES 

D SET (NO_WRITE, my_buffer) 

This statement causes myjbuffer not to be saved in a file after execution of 
a QUIT or EXIT statement. 

g SET (NO_WRITE, my_buffer, OFF) 

This statement turns off the no-write state of myjbuffer. The contents of 
the buffer are written out after execution of a QUIT or EXIT statement if 
the buffer has been modified. 
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SET (OUTPUT_FILE) 


SET (OUTPUT_FILE) 


FORMAT 

SET (OUTPUT_FILE, buffer, string) 

PARAMETERS 

OUTPUT_FILE 

A keyword indicating that SET is to control creation of an output file for 
the contents of a buffer after execution of a QUIT or EXIT statement. 

buffer 

The buffer whose contents are written to the specified file. 

String 

The file specification for the file being written out. 

The default output file is the input file name and the highest existing 
version number for that file plus 1. 

DESCRIPTION 

VAXTPU does not write out the contents of a buffer after execution of a 
QUIT or EXIT statement if the buffer has not been modified. 

If a buffer is set to NO_WRITE, a file is not written out after execution of 
a QUIT or EXIT statement even though you specified a file specification 
for the contents of the buffer with the built-in procedure SET (OUTPUT_ 
FILE). 

SIGNALED 

ERRORS 

TPU$_TOOFEW ERROR SET (OUTPUT_FILE) requires 

three parameters. 

TPU$_TOOMANY ERROR You specified more than three 

parameters. 

TPUSJNVPARAM ERROR One or more of the specified 

parameters have the wrong type. 

TPU$_BADKEY ERROR You specified an invalid keyword. 


EXAMPLE 

SET (OUTPUT_FILE, paste_buffer, "newfile.txt") 

This statement causes the output file for pastejbuffer to he 
NEWFILE.TXT. 
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SET (OVERSTRIKE) 


SET (OVERSTRIKE) 


FORMAT 

SET (OVERSTRIKE, buffer) 

PARAMETERS 

OVERSTRIKE 

A keyword specifying that SET is to control the mode of text entry. 
OVERSTRIKE means that the characters that you add to the buffer 
replace the characters in the buffer starting at the editing point and 
continuing for the length of the text that you enter. 

The default mode of text entry is INSERT. 

See also the description of the built-in procedure SET (INSERT). For 
information on how to control overstrike behavior in tabs, see SET (PAD 
OVERSTRUCK.TABS). 

buffer 

The buffer whose mode of text entry you want to set. 

SIGNALED 

ERRORS 

TPU$_TOOFEW ERROR SET (OVERSTRIKE) requires two 

parameters. 

TPU$_TOOMANY ERROR You specified more than two 

parameters. 

TPU$JNVPARAM ERROR One or more of the specified 

parameters have the wrong type. 

TPU$_BADKEY ERROR You specified an invalid keyword. 


EXAMPLE 

SET (OVERSTRIKE, my_buffer) 

This statement sets the mode for text entry in my_buffer to overstrike. 
Characters that you enter replace characters already in the buffer, starting 
at the editing point and continuing for the length of the text that you 
enter. 
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SET (PAD) 


SET (PAD) 


FORMAT 

SET (PAD, window, | }; 

PARAMETERS 

PAD 

A keyword indicating that SET is to control whether screen lines are 
padded with blanks. This ke 3 word determines whether SET pads out 
the left and right ends of lines, beyond the text on the line. \^en video 
attributes are applied to a padded window, the window has an even or 
“boxed” appearance. 

window 

The window in which lines are padded. 

ON 

Causes VAXTPU to display blanks after the last character of a record so 
that the screen line extends to the right side of the window. If there are 
not enough lines in a buffer to fill an entire window, VAXTPU displays 
blank lines (according to the video setting of the window) from the end-of- 
buffer Hne to the end of the window. 

OFF 

Causes the display of lines on the screen to stop at the last character of a 
record. When video attributes are applied to the window, the window has 
a ragged appearance on the sides. 

DESCRIPTION 

By default, VAXTPU ends a line on the screen at the end of a record, 
without adding padding blanks. The default behavior of not padding the 
screen gives maximum editing performance. You can change the default 
with SET (PAD) for special visual effects. The records in the buffer are not 
padded; only the display lines have the padding. 

SIGNALED 

ERRORS 

TPU$_TOOFEW ERROR SET (PAD) requires three 

parameters. 

TPU$_TOOMANY ERROR You specified more than three 

parameters. 

TPU$_INVPARAM ERROR One or more of the specified 

parameters have the wrong type. 

TPU$_BADKEY ERROR The keyword must be ON or OFF. 

TPU$_UNKKEYWORD ERROR You specified an unknown 

keyword. 
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SET (PAD) 


EXAMPLE 

SET (PAD, second_window, ON); 

SET (VIDEO, second_window, REVERSE); 

The first statement causes secondjuuindow to be blank padded. The second 
statement causes secondjjuindow to be displayed in reverse video. The 
window has an even right and left margin when displayed. 
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SET (PAD_OVERSTRUCK_TABS) 


SET (PAD_OVERSTRUCK_TABS) 


FORMAT 

SET (PAD_OVERSTRUCK_TABS, { 

PARAMETERS 

PAD_OVERSTRUCK_ TABS 

How tabs are handled in overstrike mode. 

ON 

Causes the insertion of one or more characters on top of a tab in overstrike 
mode, as if the text insertion mode were INSERT instead of OVERSTRIKE 
for the width of the tab. 

OFF 

Causes overstruck tabs to be replaced by the first character that is 
inserted in the buffer in overstrike mode on top of a tab. This is the 
default setting. 

DESCRIPTION 

PAD_OVERSTRUCK_TABS controls how VAXTPU handles tabs in 
overstrike mode. When earlier versions of VAXTPU overstruck a tab, 
VAXTPU inserted spaces if necessary to preserve the cursor position 
within the tab, and then replaced the tab with the character that was 
being entered. This behavior is preserved when PAD_OVERSTRUCK_ 
TABS is set OFF. 

When PAD_OVERSTRUCK_TABS is set ON, VAXTPU inserts spaces 
as necessary to preserve the cursor position within the tab of the first 
character of the text, and then inserts the text. The tab is only replaced 
when it occupies a single column. 

SIGNALED 

ERRORS 

TPU$_TOOFEW ERROR The SET (PAD_OVERSTRUCK_ 

TABS) built-in requires two 
parameters. 

TPU$_TOOMANY ERROR You specified more than two 

parameters. 

TPU$_INVPARAM ERROR One or more of the specified 

parameters have the wrong type. 

TPU$_BADKEY WARNING Only ON and OFF are allowed. 
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SET (PAD_OVERSTRUCK_TABS) 


EXAMPLES 




The following examples show what happens when PAD_OVERSTRUCK_ 
TABS is set to OFF. In these examples, the character ">" represents 
the tab, the character represents one column of white space, and an 
underscore (_) represents the cursor. 

Suppose a buffer contains the following text, with the cursor in the middle 
of white space created by a tab: 

abc>._^. .def 

Suppose the user inserts the character while PAD_OVERSTRUCK_ 
TABS is set to OFF. The white space to the left of the * is preserved. 

The tab character is removed, and the white space to the right of the * is 
not preserved. The text to the right of the collapsed white space moves 
leftward. The result is as follows: 

abc..*def 

Note that the cursor is on the "d" character. Suppose, given the same 
initial text, the user types the string "xyzzy" while PAI)_OVERSTRUCK_ 
TABS is set to OFF. The tab is removed. The text to the right of the tab 
moves leftward. The user’s new string, "xyzzy”, is written over the old 
text. The result is as follows: 

abc..xyzzy 

When PAD_OVERSTRUCK_TABS is set to ON, the text to the right of the 
tab does not move to the left when text is inserted within the tab. Instead 
of removing the tab, VAXTPU places the tab to the right of the inserted 
text if the inserted text is shorter than the length of the tab. The newly 
placed tab creates only enough white space to preserve the original column 
position of the text to the right of the tab. 

The following examples show what happens when PAD_OVERSTRUCK_ 
TABS is set to ON. In these examples, the character ">" represents the tab, 
the character represents one column of white space, and the underscore 
(-) represents the cursor. 

Suppose a buffer contains the following text, with the cursor in the middle 
of white space created by a tab: 

abc>.^..def 

Suppose the user inserts the character while PAD_OVERSTRUCK_ 
TABS is set to ON. The white space to the left of the * is preserved. The 
tab is inserted after the * character. The result is as follows: 

abc..*>.def 

Suppose, given the same initial text, the user inserts the string "xyzzy" 
while PAD_OVERSTRUCK_TABS is set to ON. lb preserve the original 
position of the text to the right of the tab, VAXTPU fills the white space 
created by the tab with characters from the new string. When the white 
space is filled, VAXTPU writes the new characters over the old characters. 
Thus, the old text does not move left or right, but rather is overwritten by 
the new text. The result is as follows: 

abc..xyzzyf 


7-440 





VAXTPU Built-in Procedures 

SET (PERMANENT) 


SET (PERMANENT) 


FORMAT 

SET (PERMANENT, buffer) 

PARAMETERS 

PERMANENT 

Specifies that a buffer cannot be deleted. By default, buffers can be 
deleted; they are not permanent. 

buffer 

The buffer that is not to be deleted. 

DESCRIPTION 

Once you use SET (PERMANENT, buffer) to make a buffer permanent, 
you cannot reset the buffer so that it can be deleted. 

SIGNALED 

ERRORS 

TPU$_TOOFEW ERROR SET (PERMANENT) requires two 

parameters. 

TPU$_TOOMANY ERROR You specified more than two 

parameters. 

TPU$_INVPARAM ERROR One or more of the specified 

parameters have the wrong type. 

TPU$_BADKEY ERROR You specified an invalid keyword. 


EXAMPLE 

SET (PERMANENT, master_buffer) 

This statement causes master Jbuffer to become a permanent buffer. 
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SET (POST_KEY_PROCEDURE) 


FORMAT 


SET (POST_KEY_PROCEDURE, string 1 


' , buffer 


, learn_sequence 


< , program 

> 

, range 


. , string2 



PARAMETERS POST_KEY_PROCEDURE 

The action taken after the code or learn sequence bound to a key is 
executed. 

string 1 

A quoted string, or a variable name representing a string constant, that 
specifies the key map list for which this procedure is called. 

buffer 

The buffer containing VAXTPU statements specifying the action to be 
taken after the code or learn sequence bound to a key is executed. SET 
(POST_KEY_PROCEDURE) compiles the statements in the buffer and 
stores the resulting program in the specified key map list. 

Iearn_sequence 

The learn sequence specifying the action to be taken after the code or 
learn sequence bound to a key is executed. The contents of a variable of 
type learn do not require compilation. SET (POST_KEY_PROCEDURE) 
stores the learn sequence in the specified key map list. 

program 

The program specifying the action to be taken after the code or learn 
sequence bound to a key is executed. The contents of a variable of type 
program do not require compilation. SET (POST_KEY__PROCEDURE) 
stores the program in the specified key map list. 

range 

The range containing VAXTPU statements specifying the action to be 
taken after the code or learn sequence bound to a key is executed. SET 
(POST_KEY_PROCEDURE) compiles the statements in the range and 
stores the resulting program in the specified key map list. 

string2 

The string cont 2 dning VAXTPU statements specifying the action to be 
taken after the code or learn sequence bound to a key is executed. SET 
(POST_KEY_PROCEDURE) compiles the statements in the string and 
stores the resulting program in the specified key map hst. 
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SET (POST_KEY_PROCEDURE) 


DESCRIPTION Postkey procedures allow an editor to perform some specified action before 

and after execution of code bound to a key. If you do not specify the third 
parameter, the postkey procedure for the specified key map list is deleted. 

Pre- and postkey procedures interact with learn sequences in the following 
order: 

1 When the user presses the key or key sequence to which the learn 
sequence is bound, VAXTPU executes the prekey procedure of that key 
if a prekey procedure has been set. 

2 For each key in the learn sequence, VAXTPU executes procedures or 
programs in the following order: 

a. VAXTPU executes the prekey procedure of that key if a prekey 
procedure has been set. 

b. VAXTPU executes the code bound to the key itself. 

c. VAXTPU executes the postkey procedure of that key if a postkey 
procedure has been set. 

3 When all keys in the learn sequence have been processed, VAXTPU 
executes the postkey procedure, if one has been set, for the key to 
which the entire learn sequence was bound. 

The pre- and postkey procedures bound to a key map list can be found by 
using the following calls to the GET_INFO built-in procedure: 

GET_INFO (k.ey__map_list__name, "pre__key_procedure") 

GET__INFO (key_map_list_name, ”post_key_procedure") 

By default, newly created key map lists do not have postkey procedures. 


SIGNALED 

ERRORS 

TPU$_TOOFEW 

ERROR 

The SET (POST_KEY_ 
PROCEDURE) built-in requires 
at least two parameters. 



TPU$_TOOMANY 

ERROR 

You specified more than three 
parameters. 


TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 


TPU$_COMPILEFAIL 

ERROR 

Compilation aborted because of 
syntax errors. 


TPU$_NOKEYMAPLIST 

WARNING 

Attempt to access an undefined 
key map list. 


EXAMPLE 

SET (POST_KEY_PROCEDURE, "tpu$key_map_list", 

'MESSAGE ("Key " + GET_INFO (LAST_KEY, "name") + " Executed")'); 

This code displays a message after the code bound to a key is executed. 
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SET (PRE_KEY_PROCEDURE) 


FORMAT 


SET (PRE_KEY_PROCEDURE, string 1 


' , buffer 


, learn_sequence 


< , program 

> 

, range 


. , string2 



PARAMETERS PRE_KEY_PROCEDURE 

The action taken before the code or learn sequence bound to a key is 
executed. 

String 1 

A quoted string, or a variable name representing a string constant, that 
specifies the key map list for which this procedure is called. 

buffer 

The buffer containing VAXTPU statements specifying the action to be 
taken before the code or leam sequence bound to a key is executed. SET 
(PRE_KEY_PROCEDURE) compiles the statements in the buffer and 
stores the resulting program in the specified key map list. 

Iearn_sequence 

The leam sequence specifying the action to be taken before the code or 
leam sequence bound to a key is executed. The contents of a variable of 
type leam do not require compilation. SET (PRE_KEY_PROCEDURE) 
stores the leam sequence in the specified key map hst. 

program 

The program specifying the action to be taken before the code or leam 
sequence bound to a key is executed. The contents of a variable of type 
program do not require compilation. SET (PRE_KEY_PROCEDURE) 
stores the program in the specified key map list. 

range 

The range containing VAXTPU statements specifying the action to be 
taken before the code or leam sequence bound to a key is executed. SET 
(PRE_KEY_PROCEDURE) compiles the statements in the range and 
stores the resulting program in the specified key map list. 

string2 

The string containing VAXTPU statements specifying the action to be 
taken before the code or leam sequence bound to a key is executed. SET 
(PRE_KEY_PROCEDURE) compiles the statements in the string and 
stores the resulting program in the specified key map list. 
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DESCRIPTION Prekey procedure allows an editor to perform some specified action before 

the execution of code bound to a key. If you do not specify the third 
parameter, the prekey procedure for the specified key map list is deleted. 

Pre- and postkey procedures interact with learn sequences in the following 
order: 

1 When the user presses the key or key sequence to which the learn 
sequence is bound, VAXTPU executes the prekey procedure of that key 
if a prekey procedure has been set. 

2 For each key in the learn sequence, VAXTPU executes procedures or 
programs in the following order: 

a. VAXTPU executes the prekey procedure of that key if a prekey 
procedure has been set. 

b. VAXTPU executes the code bound to the key itself. 

c. VAXTPU executes the postkey procedure of that key if a postkey 
procedure has been set. 

3 When all keys in the learn sequence have been processed, VAXTPU 
executes the postkey procedure, if one has been set, for the key to 
which the entire learn sequence was bound. 

The prekey procedure or postkey procedure bound to a key map list can be 
found by using the following calls to the GETJNFO built-in procedure: 

GET__INFO (key__map_list_name, "pre_key_procedure") ; 

GET_INFO (key_map__list_name, "post_key_j)rocedure") ; 

By default, newly created key map lists do not have prekey procedures. 


SIGNALED 

ERRORS 

TPU$_TOOFEW 

ERROR 

The SET (PRE_KEY_ 
PROCEDURE) built-in requires 
at least two parameters. 


TPU$_TOOMANY 

ERROR 

You specified more than three 
parameters. 


TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 


TPU$_COMPILEFAIL 

ERROR 

Compilation aborted because of 
syntax errors. 


TPU$_NOKEYMAPLIST 

WARNING 

Attempt to access an undefined 
key map list. 


EXAMPLE 

SET (PRE_KEY_PROCEDURE, "tpu$key_map_list", 

'MESSAGE ("Working 

This code displays a message before the code boimd to a key is executed. 
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SET (PROMPT_AREA) 


FORMAT 

r NONE 

BOLD 

SET (PROMPT AREA, integerl, integer2, < BLINK W 

REVERSE 

1 UNDERLINE J 

PARAMETERS 

PROMPT_AREA 

An area on the screen in which the prompts generated by the built-in 
procedure READ_LINE are displayed. 

By default, there is no prompt area. 

integerl 

The screen line number at which the prompt area starts. 

integer2 

The number of screen lines in the prompt area. 

NONE 

Applies no video attributes to the characters in the prompt area. 

BOLD 

Causes the characters in the prompt area to be bolded. 

BLINK 

Causes the characters in the prompt area to blink. 

REVERSE 

Causes the characters in the prompt area to be displayed in reverse video. 

UNDERLINE 

Causes the characters in the prompt area to be underlined. 

DESCRIPTION 

If the prompt area overlaps a line of a window that is visible on the screen, 
the line is erased when the built-in procedure READ_LINE is executed. 
When the execution of READ_LINE is completed, the line is restored. If 
the prompt area does not overlap any windows, the prompt area continues 
to display the READ__LINE prompt and your input until new information 
is sent to the prompt area. 

If you have a multiple-line prompt area and your terminal has hardware 
scrolling capabilities, the first prompt appears on the last line of the 
prompt area and as subsequent prompts are issued, the previous prompts 
scroll up to make room for new ones. If there are more prompts than there 
are prompt-area lines, the extra prompts are scrolled out of the window. 
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SIGNALED 

ERRORS 


EXAMPLE 

SET (PROMPT_AREA, 


If your terminal does not have hardware scrolling capabilities, prompts are 
displayed starting at the first line in the prompt area. When the prompt 
area is filled, display starts again at the first line in the prompt area. 


TPU$_TOOFEW 

ERROR 

SET (PROMPT_AREA) requires 
four parameters. 

TPU$_TOOMANY 

ERROR 

You specified more than four 
parameters. 

TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 

tpu$_badkey 

ERROR 

The keyword must be NONE, 
BOLD, BLINK, REVERSE, or 
UNDERLINE. 

TPU$_UNKKEYWORD 

ERROR 

You have specified an unknown 
keyword. 

TPU$_BADFIRSTLINE 

WARNING 

Prompt area must not start off 
screen, or be less than one line 
long. 

TPU$_BADPROMPTLEN 

WARNING 

Prompt area must not extend off 
screen. 


24, 1, REVERSE) 

This statement causes the prompt area to be screen line number 24. It is 
one line and is displayed in reverse video. 
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SET (RECORD_ATTRIBUTE) 



Sets or alters any of three possible attributes for the specified record or 
records. The attributes you can set for a record are its left margin, its 
modifiability, and its visibility. 

FORMATS 

SET (RECORD_ATTRIBUTE, 1 range | MARGIN J' 

1 buffer ) ^ 

( display_settingjnteger "I. 

\ marginjsettingjnteger J' 

or 

{ marker, \ ( ON ) 

SET (RECORD_A1TRIBUTE, 1 range, \ MODIFIABLE, | }; 

1 buffer, ) 

PARAMETERS 

RECORD_ATTRIBUTE 

A ke 5 rword indicating that the SET built-in is being used to specify or 
change a record attribute. 

marker 

The marker indicating the record whose attribute you want to set. 

range 

The range containing the records whose attribute you want to set. The 
record attribute is applied to all records in the range. Records that are 
partially within the range will be modified. 

buffer 

The buffer containing the records for which you want to set an attribute. 
The record attribute is applied to all records in the buffer. 

DISPLAY_VALUE 

A keyword indicating that you want to affect the visibility of the records. 

If you specify the DISPLAY_VALUE keyword as the third parameter, 
you must specify for the fourth parameter an integer providing a display 
setting. 

LEFT_MARGIN 

A ke 5 rword indicating that you want to specify the left margin for the 
specified records. If you specify the LEFT_MARGIN keyword as the third 
parameter, you must specify for the fourth parameter an integer providing 
a left margin value. 

display_setting_integer 

An integer value from -127 to +127. This is the display setting. To 
determine whether a record is to be visible or invisible in a given window, 
VAXTPU compares the record’s display setting to the window’s display 
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setting. (A window’s display setting is specified with SET (DISPLAY_ 
VALUE).) If the record’s setting is greater than or equal to the window’s 
setting, VAXTPU makes the record visible in that window; otherwise, 
VAXTPU makes the record invisible. 

marginjsettingjnteger 

An integer that is the column at which the left margin should be set. The 
value must be between 1 and the value of the right margin minus 1. (The 
maximum valid value for the right margin is 32767.) 

MODIFIABLE 

A ke 3 nvord indicating that you want to determine whether the specified 
records are modifiable. If you specify the MODIFIABLE ke 3 nvord as 
the third parameter, you must specify either ON or OFF as the fourth 
parameter. 

ON 

A ke 3 rword making records modifiable. Note, if a buffer is modifiable, 
you can use SET (RECORD_ATTRIBUTE) to make a record in the biiffer 
unmodifiable (with ke 3 nvord OFF). If a buffer is unmodifiable and you use 
SET (RECORD_ATTRIBlJTE) to make a record in the buffer modifiable 
(with keyword ON), VAXTPU marks the record as modifiable but does not 
allow modifications to the record until the buffer is made modifiable. 

OFF 

A keyword making records unmodifiable. 

DESCRIPTION 

With each call to SET (RECORD_ATTRIBUTE), you can set only one 
attribute. For example, you cannot change visibility and modifiabiUty 
using just one call. To set more than one record attribute, use multiple 
calls to SET (RECORD.ATTRIBUTE). 

When you set an attribute for multiple records, each record gets the same 
value. For example, if you specify a range of records and a value for the 
left margin attribute, all records in the range receive the same left margin 
value. 

You cannot change the left margin of an unmodifiable record. You can 
change the display value of a record at any time. 

SIGNALED 

ERRORS 

TPU$_TOOMANY ERROR You specified too many 

parameters. 

TPU$_TOOFEW ERROR You specified too few parameters. 

TPU$JNVPARAM ERROR The third parameter must be a 

keyword. 

TPU$__ARGMISMATCH ERROR The second or fourth parameter 

has an incorrect type. 

TPU$_BADKEY WARNING You have specified an invalid 

keyword. 
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TPU$_BADDISPVAL WARNING Display values must be between 

-127 and +127. 

TPU$_BADMARGINS WARNING You have specified an illegal left 

margin value. 


EXAMPLES 

Q SET (MODIFIABLE, bufl, OFF); 

rl:= CREATE_RANGE (BEGINNING_OF(buf1), END_OF(buf1), REVERSE); 

SET (RECORD_ATTRIBUTE, rl, MODIFIABLE, OFF) ; 

SET (RECORD_ATTRIBUTE, rl, MODIFIABLE, ON); 

SET (MODIFIABLE, bufl, ON) ; 

This code fragment uses statements that change buffer modifiability 
and record modifiability independently. Note that you can turn on 
the modifiability of a record or range of records even when the buffer’s 
modifiability is turned off. 

g SET (RECORD_ATTRIBUTE, CURRENT_BUFFER, LEFT_MARGIN, 3); 

This statement sets the left margin of all records in the current buffer to 
column 3. 


SET (DISPLAY_VALUE, CURRENT_WINDOW, 0); 

SET (RECORD_ATTRIBUTE, SELECT_RANGE, -1); 

These statements make the records in the range select_range invisible in 
the current window. 

SET (RECORD_ATTRIBUTE, MARK (FREE_CURSOR), MODIFIABLE, OFF); 

This statement makes the current record unmodifiable. 


7-450 





VAXTPU Built-In Procedures 

SET (RESIZE_ACTION) 


SET (RESIZE_ACTION) 

Specifies code to be executed when a resize event has occurred. Specifying 
a resize action routine overrides any previous resize action routines that have 
been defined. 


FORMAT 


SET (RESIZE_ACTION 


' buffer 


learnjsequence 


program 

► 

range 


string 


NONE J 



PARAMETERS RESIZE_ACTION 

A keyword directing VAXTPU to set an attribute related to a resize action 
routine. 

buffer 

The buffer that specifies the actions that VAXTPU should take whenever 
it is notified of a resize event. 

Iearn_sequence 

The learn sequence that specifies the actions that VAXTPU should take 
whenever it is notified of a resize event. 

program 

The program that specifies the actions that VAXTPU should take whenever 
it is notified of a resize event. 

range 

The range that specifies the actions that VAXTPU should take whenever it 
is notified of a resize event. 

string 

The string that specifies the actions that VAXTPU should take whenever 
it is notified of a resize event. 

NONE 

A keyword directing VAXTPU to delete the resize action routine. If you 
specify this keyword or do not specify the parameter at all, the application 
is not notified when a resize event occurs. 
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SIGNALED 

ERRORS 


EXAMPLE 

SET (RESIZE_ACTION, 


TPU$JNVPARAM 

ERROR 

One of the parameters was 
specified with data of the wrong 
type. 

TPU$_NORETURNVALUE 

ERROR 

SET (RESIZE_ACTION) cannot 
return a value. 

TPU$_REQUIRESDECW 

ERROR 

You can use the SET (RESIZE_ 
ACTION) built-in only if you are 
using DECwindows VAXTPU. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
SET (RESIZE_ACTION) built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed 
to the SET (RESIZE_ACTION) 
built-in. 


"eve$$resize action"); 


This statement specifies the procedure EVE$$RESIZE_ACTION as the 
resize routine. To see this statement used in an initializing procedure, see 
the example in the description of the SET (SCREEN_LIMITS) built-in. 
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SET (REVERSE) 


FORMAT SET (REVERSE, buffer) 


PARAMETERS REVERSE 

The direction of the buffer. REVERSE means to go toward the beginning 
of the buffer. 

The default direction for a buffer is forward. 

buffer 

The buffer whose direction you want to set. 


DESCRIPTION 

Interfaces use this feature to keep track of direction for searching or 
movement. 

SIGNALED 

ERRORS 

TPU$_TOOFEW 

ERROR 

SET (REVERSE) requires two 
parameters. 


TPU$_TOOMANY 

ERROR 

You specified more than two 
parameters. 


TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 


tpu$_badkey 

ERROR 

You specified an invalid keyword. 


EXAMPLE 


SET (REVERSE, my_buffer) 

This statement causes the direction of the buffer to be toward the 
beginning of the buffer. 
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SET (RIGHT_MARGIN) 


FORMAT 

SET (RIGHT_MARGIN, buffer, integer) 

PARAMETERS 

RIGHT_MARGIN 

The right margin of a buffer. 

buffer 

The buffer in which the right margin is being set. 

integer 

The column at which the right margin is set. 

DESCRIPTION 

The SET (RIGHT_MARGIN) built-in procedure allows you to change only 
the right margin of a buffer. 

Newly created buffers receive a right margin of 80 if a template buffer is 
not specified on the call to the CREATE_BUFFER built-in procedure. If 
a template buffer is specified, the right margin of the template buffer is 
used. 

Use SET (RIGHT_MARGIN) to override the default right margin. 

The buffer margin settings are independent of the terminal width or 
window width settings. 

The built-in procedure FILL uses these margin settings when it fills the 
text of a buffer. 

The SET (RIGHT_MARGIN) built-in procedure controls the buffer margin 
setting even if the terminal width or window width is set to something 
else. 

The value of the right margin must be less than the maximum record 
size for the buffer, and greater than the left margin value. You can use 
the built-in procedure GET_INFO (buffer, “record_size”) to find out the 
maximum record size of a buffer. 

If you want to use the margin settings of 2 m existing buffer in a user- 
written procedure, the statements GETJNFO (buffer, “left_margin”) 
and GETJNFO (buffer, “right_margin”) return the values of the margin 
settings in the specified buffer. 

SIGNALED 

ERRORS 

TPU$_TOOFEW ERROR The SET (RIGHT_MARGIN) 

built-in requires three parameters. 

TPU$_TOOMANY ERROR You specified more than three 

parameters. 
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TPU$_INVPARAM ERROR One or more of the specified 

parameters have the wrong type. 

TPU$_BADMARGINS WARNING Right must be greater than left; 

both must be greater than zero. 


EXAMPLES 

D SET (RIGHT_MARGIN, mY_buffer, 132) 

This statement causes the right margin of the buffer represented by the 
variable my_buffer to be changed. The right margin of the buffer is set to 
132. The left margin is unchanged. 

g SET (RIGHT_MARGIN, CURRENT_BUFFER, 70) 

This statement causes the right margin of the current buffer to be changed 
to 70. As above, the left margin is unchanged. 
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SET (RIGHT_MARGIN_ACTION) 


FORMAT 


SET (RIGHT_MARGIN_ACTION, bufferl 


' buffer2 


learnjsequence 


< program 

> 

range 


. string 



PARAMETERS RIGHT_MARGIN_ACTION 

Refers to the action taken when the user presses a self-inserting key while 
the cursor is to the right of a buffer’s right margin. A self-inserting key is 
one that is associated with a printable character. 

bufferl 

The buffer in which the right margin action routine is being set. 

buffer2 

A buffer containing the VAXTPU statements to be executed when the user 
presses a self-inserting key while the cursor is to the right of a buffer’s 
right margin. 

Iearn_sequence 

A learn sequence that is to be replayed when the user presses a self- 
inserting key while the cursor is to the right of a buffer’s right margin. 

program 

A program that is to be executed when the user presses a self-inserting 
key while the cursor is to the right of a buffer’s right margin. 

range 

A range that contains VAXTPU statements that are to be executed when 
the user presses a self-inserting key while the cursor is to the right of a 
buffer’s right margin. 

String 

A string that contains VAXTPU statements that are to be executed when 
the user presses a self-inserting key while the cursor is to the right of a 
buffer’s right margin. 


DESCRIPTION The SET (RIGHT_MARGIN_ACTION) built-in procedure allows you to 

specify an action to be taken when the user attempts to insert text to 
the right of the right margin of a line. If the third parameter is not 
specified, the right margin action routine is deleted. If no right margin 
action routine has been specified, the text is simply inserted at the current 
position after any necessary padding spaces. 

Newly created buffers do not receive a right margin action routine if a 
template buffer is not specified on the call to the CREATE_BUFFER built- 
in procedure. If a template buffer is specified, the right margin action 
routine of the template buffer is used. 
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The right margin action routine only affects text entered from the 
keyboard or a leam sequence. Inserting text into a buffer to the right 
of the right margin using the COPY_TEXT or MOVE_TEXT built-in 
procedures does not trigger the right margin action routine. 


ERROR The SET (RIGHT_MARGIN_ 

ACTION) built-in requires at least 
two parameters. 

ERROR You specified more than three 

parameters. 

ERROR One or more of the specified 

parameters have the wrong type. 

ERROR Compilation aborted because of 

syntax errors. 

EXAMPLES 

D SET (RIGHT_MARGIN_ACTION, CURRENT_BUFFER, "fill_current_line") 

This statement causes the procedure FILL_CUKRENT_LINE to be 
executed when the user attempts to type a character to the right of 
the right margin of the current hne. A typical right margin action routine 
invokes the FILL built-in to fill the current line and force text to the right 
of the right margin to a new line. 

g SET (RIGHT_MARGIN_ACTION, CURRENT_BUFFER) 

This statement deletes any right margin action routine that may be 
defined for the current buffer. If the user attempts to type a character to 
the right of the right margin of the current line, the text is inserted with 
spaces padding the text from the end of the line. 


SIGNALED 

ERRORS 


TPU$_TOOFEW 

TPU$_TOOMANY 

TPU$JNVPARAM 

TPU$_COMPILEFAIL 
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SET (SCREEN_LIMITS) 



Specifies the minimum and maximum allowable sizes for the VAXTPU screen 
during resize operations. VAXTPU passes these limits to the DECwindows 
window manager, which is free to use or ignore the limits. 

FORMAT 

SET (SCREEN_LIMITS, array) 

PARAMETERS 

SCREEN_UMITS 

A keyword directing VAXTPU to pass hints to the DECwindows window 

manager about screen size. 

array 

An integer-indexed array using four elements to specify hints for the 

minimum and maximum screen width and length. The array indices and 

their corresponding elements are as follows: 

1 The minimum screen width, in columns. This value must be at least 

0 and less than or equal to the maximum screen width. The default 
value is 0. 

2 The minimum screen length, in lines. This value must be at least 0 
and less than or equal to the maximum screen length. The default 
value is 0. 

3 The maximum screen width, in columns. This value must be greater 
than or equal to the minimum screen width and less than or equal to 
255. The default value is 255. 

4 The maximum screen length, in lines. This value must be greater than 
or equal to the minimum screen length and less than or equal to 255. 
The default value is 255. 

SIGNALED 

ERRORS 

TPU$_BADVALUE WARNING An integer parameter was 

specified with a value outside 
the valid range. 

TPU$_MAXVALUE WARNING You specified a value higher than 

the maximum allowable value. 

TPU$_MINVALUE WARNING You specified a value lower than 

the minimum allowable value. 

TPU$_EXTRANEOUSARGS ERROR One or more extraneous 

arguments have been specified 
for a DECwindows built-in. 

TPU$_INVPARAM ERROR One of the parameters was 

specified with data of the wrong 


type. 
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TPU$_NORETURNVALUE 

ERROR 

SET (SCREEN_LIMITS) cannot 
return a value. 

TPU$_REQUIRESDECW 

ERROR 

You can use the SET (SCREEN_ 
LIMITS) built-in only if you are 
using DECwindows VAXTPU. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
SET (SCREEN_LIMITS) built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed 
to the SET (SCREEN_LIMITS) 
built-in. 

TPU$_REQARGSMISSING 

ERROR 

One or more required arguments 
are missing. 


EXAMPLE 

PROCEDURE eve$$decwindows_init ! Module Initialization 

LOCAL temp_array; 

eve$x_decwindows_active := GET__INFO (SCREEN, "decwindows"); 


IF NOT eve$x_decwindows__active 
THEN 

RETURN (FALSE) 

ENDIF; 

! The following statements set the package up to handle resize actions. 

temp_array := CREATE_ARRAY (4); 
templarray {1} := 20; ! Minimum width. 

temp_array {2} := 6; ! Minimum height. 

temp_array {3} := 250; ! Maximum width. 

temp_array {4} := 100; ! Maximum height. 

SET (SCREEN_LIMITS, temp_array); 

SET (RESIZE__ACTION, ”eve$$resize_action"); 

SET (ENABLE_RESIZE, ON); 


ENDPROCEDURE; 


These statements show one possible way that a layered application can 
use the SET (SCREEN_LIMITS) built-in. The statements are a portion of 
the EVE procedure EVE$$DECWINDOWS_INIT. You can find the original 
version in SYS$EXAMPLES:EVE$DECWINDOWS.TPU. 

The procedure EVE$$DECWINDOWS_INIT is the module initialization 
procedure for the package EVE$DECWINDOWS. 
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SET (SCREEN_UPDATE) 



Turns on or turns off support for screen updating. For more information on 
screen updating, see Section 6.2. 

FORMAT 

M OFF } " * (SCREEN_UPDATE, { }; 

PARAMETERS 

SCREEN_UPDATE 

A ke 3 rword directing VAXTPU to set an attribute of screen updating. 

ON 

A ke 5 rword indicating that screen updating is enabled. 

OFF 

A ke 3 rword indicating that screen updating is disabled. 

return value 

A variable containing the keyword value ON or OFF. The keyword specifies 
whether VAXTPU screen updating support was enabled or disabled before 
the current SET (SCREEN_UPDATE) statement was executed. Using the 
returned variable, you can enable or disable screen updating and then 
reset the support to its previous setting without having to make a separate 
call to fetch the previous setting. 

DESCRIPTION 

When you set SCREEN_UPDATE on, the screen manager is immediately 
called to update the screen. The extent of the update depends on the 
built-ins that have been used since the last screen update. The update 
may range from a complete screen refresh to an updating of the existing 
text on the screen. 

For more information on screen updating, see Section 6.2. 

SIGNALED 

ERRORS 

TPU$_BADKEY WARNING The keyword must be ON or OFF. 

TPU$JNVPARAM ERROR One or more of the specified 

parameters have the wrong type. 

TPU$_TOOFEW ERROR SET (SCREEN__UPDATE) requires 

two parameters. 

TPU$_TOOMANY ERROR You specified more than two 

parameters. 

TPU$_UNKKEYWORD ERROR You have specified an unknown 

keyword. 
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EXAMPLE 

SET (SCREEN_UPDATE, 


OFF) 

This statement causes screen updating to be turned off. When you design 
an editing interface, you may want to use this statement to prevent some 
intermediate processing steps from appearing on the screen. 
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SET (SCROLL_BAR) 



Enables a horizontal or vertical scroll bar for the specified window. 

FORMAT 

1 { ^ SCROLL^BAR. «indo«, { }. 

{Z)> 

PARAMETERS 

SCROLL_BAR 

A keyword directing VAXTPU to enable or disable a scroll bar in a 
VAXTPU window. 

window 

The window in which the scroll bar does or does not appear. 

HORIZONTAL 

A keyword directing VAXTPU to enable or disable a horizontal scroll bar. 

VERTICAL 

A keyword directing VAXTPU to enable or disable a vertical scroll bar. 

ON 

A keyword indicating that the scroll bar is to be visible in the specified 
window. 

OFF 

A keyword indicating that the scroll bar is not to be visible in the specified 
window. 

return value 

integer The value 0 if an error prevents VAXTPU from associating a 

widget with the window. 

widget The widget instance implementing the vertical or horizontal 

scroll bar associated with a window. 

DESCRIPTION 

Scroll bars represent the location of the editing point in the buffer. By 
dragging the scroll bar's slider, the user can reposition the editing point in 
the buffer mapped to the window. Scroll bars are unique among VAXTPU 
widgets in the following respects: 

• Each scroll bar widget is associated with a specific VAXTPU window. 

• Instead of handling scroll widgets at the application level, you can 
direct VAXTPU to handle resizing and repositioning of the scroll bar 
slider. VAXTPU always handles sizing and positioning of the scroll bar 
itself. 
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Note that windows having fewer than four hnes of text cannot display a 
vertical scroll bar. Similarly, a window less than four columns wide cannot 
display a horizontal scroll bar. 

SET (SCROLL_BAR) returns the scroll bar widget, or 0 if an error 
prevents VAXTPU from associating a widget with the window. 

By default, VAXTPU creates its windows without any scroll bars; using 
SET (SCROLL_BAR) with the kesrword ON overrides the default. To make 
a scroll bar invisible after it has been placed in a window (for example, 
to allow the user of a layered application to turn off scroll bars), use SET 
(SCROLL_BAR) with the keyword OFF. 

When the size of a VAXTPU window changes, VAXTPU automatically 
adjusts the scroll bar to fit the new window size. If a window becomes too 
small to support a scroll bar, VAXTPU turns off the scroll bar. However, 
if the window subsequently becomes larger, VAXTPU automatically turns 
the scroll bar back on. 

The height of a vertical scroll bar represents the total number of lines in 
the buffer mapped to the window. 

The width of a horizontal scroll bar represents the greater of the following: 

• The width of the widest line in the set of lines visible in the window. 
"Width" means the distance from the first character on the fine to the 
last character, regardless of whether all characters on the line are 
visible. 

• In a case where none of the lines in the set of lines visible in the 
window has text extending all the way to the rightmost window 
column, the width of the widest line from the first character on the 
line to the rightmost window column. 

Note that the horizontal scroll bar represents only the lines that are 
visible in the window, not all the lines in the buffer mapped to the window. 


SIGNALED 

ERRORS 


TPU$_BADKEY 

WARNING 

You specified an invalid keyword 
as a parameter. 

TPU$JNVPARAM 

ERROR 

One of the parameters was 
specified with data of the wrong 
type. 

TPU$_REQUIRESDECW 

ERROR 

You can use the SET (SCROLL_ 
BAR) built-in only if you are using 
DECwindows VAXTPU. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
SET (SCROLL_BAR) built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the SET (SCROLL_BAR) built-in. 
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EXAMPLE 

vertical_bar := SET (SCROLL_BAR, CURRENT_WINDOW, VERTICAL, ON); 

This statement turns on a vertical scroll bar in the current window. 

For sample code using the SET (SCROLL_BAR) built-in, see Example B-7. 
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SET (SCROLL_BAR_AUTO_THUMB) 



Enables or disables automatic adjustment of the scroll bar slider. 

FORMAT 

SET (SCROLL_BAR_AUTO_THUMB, window, { }- 

(ON 

1 OFF y 

PARAMETERS 

SCROLL_BAR_AUTO_THUMB 

A keyword directing VAXTPU to enable or disable automatic adjustment 
of the scroll bar slider in a VAXTPU window. 

window 

The window whose scroll bar slider you want VAXTPU to adjust. 

HORIZONTAL 

A keyword directing VAXTPU to set the slider on a horizontal scroll bar. 

VERTICAL 

A keyword directing VAXTPU to set the slider on a vertical scroll bar. 

ON 

A keyword directing VAXTPU to enable automatic adjustment of the scroll 
bar slider. 

OFF 

A keyword directing VAXTPU to disable automatic adjustment of the scroll 
bar slider. 

DESCRIPTION 

By default, SET (SCROLL3AR_AUTO_THUMB) is set to ON and 
VAXTPU automatically manages a window’s scroll bar slider in the 
following ways: 

• Adjusts the size of the slider as the user adds, deletes, or moves text, 
so that the slider size represents the amount of visible text in relation 
to the total amount of text 

• Adjusts the size of the slider whenever the size of the window and 
the size of the scroll bar change, so that the slider size remains 
proportional to the scroll bar size 

• Adjusts the position of the slider as the user adds, deletes, or moves 
text, so that the slider shows whether the current buffer or line 
contains text not visible on the screen and, if so, where the invisible 
text is in relation to the visible text 
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When the scroll bar slider is adjusted automatically, the width of the slider 
in a horizontal scroll bar represents the width of the window. For example, 
the size of the slider changes when the window width is changed from 80 
to 132 columns or the reverse. The position of the slider changes when the 
window is shifted left or right. The height of the shder in a vertical scroll 
bar represents the height of the window. 

If you do not want VAXTPU to adjust the scroll bar slider automatically 
or if you want to change the size or position of the slider, specify the OFF 
kesnvord. For more information about calculating the size and position of 
the slider, see the description of the SET (SCROLL_BAK) built-in. 

Note that you cannot disable VAXTPU’s automatic adjustment of the scroll 
bar itself. VAXTPU always adjusts the scroll bar to the size of the window. 


SIGNALED 

ERRORS 


TPU$_BADKEY 

WARNING 

You specified an invalid keyword 
as a parameter. 

TPU$JNVPARAM 

ERROR 

One of the parameters was 
specified with data of the wrong 
type. 

TPU$_NORETURNVALUE 

ERROR 

SET {SCROLL_BAR_AUTO_ 
THUMB) cannot return a value. 

TPU$_REQUIRESDECW 

ERROR 

You can use the SET (SCROLL 
BAR_AUTO_THUMB) built-in only 
if you are using DECwindows 
VAXTPU. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to 
the SET (SCROLL BAR AUTO 
THUMB) built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the SET (SCROLL BAR AUTO 
THUMB) built-in. 


EXAMPLE 

vertical_bar := SET (SCROLL_BAR_AUTO_THUMB, CURRENT_WINDOW, VERTICAL, ON); 

This statement turns on automatic adjustment of the vertical scroll bar’s 
shder in the current window. 

For sample code using the SET (SCROLL_BAR_AUTO_THUMB) built-in, 
see Example B-7. 
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SET (SCROLLING) 


FORMAT 

SET (SCROLLING, window, | integerl, integer2, integers) 

PARAMETERS 

SCROLLING 

This keyword refers to the upward or downward movement of existing 
lines in a window to make room for new lines at the bottom or top of the 
window. When a window is scrolled, the cursor position remains in the 
same column, but the screen line that the cursor is on may change. 

window 

The window in which the scrolling limits are being set. 

ON 

Causes scrolling of the text in a window to be turned on. This is the 
default value for the third parameter if the terminal supports scrolling. 

OFF 

Causes scrolling of the text in a window to be turned off. The screen is 
completely repainted each time a scroll would otherwise take place. This is 
the default value for the third parameter if the terminal does not support 
scrolling. 

integerl 

The offset from the top screen line of a window. The offset identifies the 
top limit of an area in which the cursor can move as it tracks the editing 
point. If the cursor is forced to move above this screen line to track the 
editing point, lines in the window move downward so that the cursor stays 
within the limits of the scroll margins. If you reach the beginning of the 
buffer, the text is no longer scrolled. 

The value you specify for this parameter must be greater than or equal to 
zero and less than or equal to the number of lines in the window. 

integer2 

The offset from the bottom screen line of a window. The offset identifies 
the bottom limit of an area in which the cursor can move as it tracks the 
editing point. If the cursor is forced to move below this screen line to track 
the editing point, lines in the window move upward so that the cursor 
stays within the limits of the scroll margins. If you reach the end of the 
buffer, the text is no longer scrolled. 

The value you specify for this parameter must be greater than or equal to 
zero £ind less than or equal to the number of lines in the window. 

integers 

The number indicating how many lines from the top or the bottom scroll 
margin the cursor should be positioned after a window is scrolled. For 
example, if the bottom scroll margin is screen line 14 and integers has a 
value of 0, the cursor is positioned on screen line 14 after text is scrolled 
upward. However, if integers has a value of 3, the cursor is positioned on 
screen line 11. 
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The value you specify for this parameter must be greater than or equal to 
zero and less than or equal to the number of lines in the window. 

You cannot specify a value that would position the cursor outside the 
window. That is, integerl -i- integers or integer2 + integers must be less 
than the height of the window. For example, if the window is 10 lines 
long and integerl is set at 3, you cannot specify a value of 7 or more for 
integers. Such a specification would place the cursor outside the window. 

Note that if you use the SET (SCROLLING) built-in from within EVE by 
way of the TPU command, EVE may override the value you specify for this 
parameter. 

DESCRIPTION 

This built-in procedure is used to modify the scrolling action of a window. 

If the terminal on which you are running VAXTPU supports scrolling, you 
can use the SET (SCROLLING) built-in to turn scrolling on or off. If the 
terminal does not support scrolling, scrolling will always be off. If scrolling 
is off, the window is repainted every time a scroll would otherwise occur. 

The SET (SCROLLING) built-in also defines scroll margins using integerl 
and integer2. If the cursor is moved above the top scroll margin or 
below the bottom scroll margin using CURSOR_\^RTICAL, MOVE_ 
HORIZONTAL, MOVE_VERTICAL, POSITION, or a text manipulation 
built-in, then SET (SCROLLING) moves the cursor by the number of lines 
specified in integers. 

You must provide values for integerl and integer2 that leave at least one 
line in the window unaffected by either scroll margin. That is, integerl + 
integer2 must be less than the height of the window. For example, if you 
have a window that is ten lines tall, you cannot specify a value of 5 for 
the top scroll margin and a value of 5 for the bottom scroll margin. Such 
a specification leaves no area of the window that is not within a scroll 
margin. 

You can move the cursor above or below a scroll margin under certain 
circumstances. If CROSS_WINDOW_BOUNDS is set to off, CURSOR.. 
VERTICAL does not cause scrolling when the cursor reaches a scroll 
margin. If you are moving backward through the file and the top line of 
the buffer is already visible on the screen, the top scroll margin is ignored. 
If you are moving forward through the file and the bottom line of the 
buffer is already visible on the screen, the bottom scroll margin is ignored. 

If using the ADJUST.WINDOW built-in makes the window so much 
smaller that the scroll margins overlap, VAXTPU automatically reduces 
the scroll margins proportionally to fit the new window. If you use 
ADJUST_WINDOW to make a window larger, VAXTPU does not adjust 
the scroll margins. 
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SIGNALED 

ERRORS 


TPU$_TOOFEW 

ERROR 

SET (SCROLLING) requires at 
least six parameters. 

TPU$_TOOMANY 

ERROR 

You specifiecJ more than six 
parameters. 

TPU$JNVPARAM 

ERROR 

One or more of the specifiecJ 
parameters has the wrong type. 

TPU$_UNKKEYWORD 

ERROR 

You have specified an unknown 
keyword. 

TPU$_BADKEY 

ERROR 

Keyword must be either ON or 
OFF. 

TPU$_BADMARGINS 

ERROR 

You have specified values for the 
top margin, bottom margin, and 
cursor movement that exceed the 
dimensions of the window. 

TPU$_BADVALUE 

ERROR 

Integer values must be from 0 to 
255. 


EXAMPLES 

D SET (SCROLLING, new_window, ON, 0, 0, 2) 

T his statement turns on scrolling in the window newjvindow. The 
statement sets the top and bottom scroll margins to 0. This means that 
the cursor can be moved all the way to the top or bottom of the window 
before new text is scrolled into the window. Finally, the statement causes 
VAXTPU to place the cursor two lines down from the top or up from the 
bottom of the window when scrolling is completed. 

§ SET (SCROLLING, new_window, ON, 0, 0, 20) 

This statement demonstrates how to set scrolhng if you want VAXTPU 
to present an entire window of new text each time a scroll occurs. If the 
variable new_window is 21 lines long, this statement causes VAXTPU to 
scroll all the text in the window off the top or bottom of the screen when 
you move the cursor to the top or bottom of the screen. This statement 
scrolls 20 new lines of text into the window. 

Note that this statement does not produce a new window of text if you 
issue the statement from within EVE using the TPU command and move 
the cursor using the up arrow key or the down arrow key. 
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SET (SELFJNSERT) 


FORMAT 

SET (SELFJNSERT. string, ( }; 

PARAMETERS 

1 

SELFJNSERT 

A keyword specifying whether a character is inserted into the buffer when 
the user presses a key with the following characteristics: 

• Associated with a printable character 

• Not bound to a procedure or program 

String 

A string specifying the key map hst in which the behavior of undefined 
keys associated with printing characters is to be set. 

ON 

Causes the printable characters to be inserted when no procedures are 
boimd to them, while the specified key map list is active. This is the 
default. 

OFF 

Causes the UNDEFINED_KEY procedure to be called when these 
characters are entered. If an undefined key procedure has not been 
specified, VAXTPU merely displays a warning message when the user 
presses an undefined, printable key. You can specify an undefined key 
procedure using the SET (UNDEFINED_KEY) built-in. 

DESCRIPTION 

SET (SELFJNSERT) lets you control what happens when the user presses 
an undefined key associated with a printable character. If SELFJNSERT 
is set ON and the user presses an undefined key associated with a 
printable character, the character is inserted into the current buffer at 
the current cursor position. If SELFJNSERT is turned off, printable 
characters whose keys are not defined in any key maps in the key map 
list bound to the current buffer are considered undefined. These undefined 
keys cause either the message “key has no definition” to be displayed, or 
some user-defined action to occur. 

The default result for pressing an undefined key associated with a 
printable character procedure is that the character is inserted. The 
default condition for SET (SELFJNSERT) is ON. The default behavior, if 
SET (SELF.INSERT) is OFF, is to call the UNDEFINED_KEY procedure. 
See the description of the built-in procedure SET (UNDEFINED_KEY). 

For more information on how to define what happens when SET (SELF_ 
INSERT) is turned off, see the description of the built-in procedure SET 
(UNDEFINED.KEY) in this chapter. 
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SIGNALED 

ERRORS 

TPU$_NOKEYMAPLIST 

WARNING 

You attempted to access an 
undefined key map list. 


TPU$_TOOFEW 

ERROR 

SET (SELFJNSERT) requires 
three parameters. 


TPU$_TOOMANY 

ERROR 

You specified more than three 
parameters. 


TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 


TPU$_BADKEY 

ERROR 

You specified an invalid keyword. 


EXAMPLE 

PROCEDURE toggle_self_insert 
LOCAL current_key_map_list; 

current_key__map_list := GET_INFO (CURRENT__BUFFER, "key_map_list”) ; 

IF GET_INFO (current_key_map_list, "self__insert") 

THEN 

SET (SELF_INSERT, current_key__map___list, OFF) 

ELSE 

SET (SELF_INSERT, current_key_map_list, ON) 

ENDIF; 

ENDPROCEDURE; 

This procedure toggles the ON and OFF setting of SELFJNSERT for the 
key map list bound to the current buffer. 
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SET (SHIFT_KEY) 


FORMAT 

SET (SHIFT_KEY. keyword [, string ]l) 

PARAMETERS 

SHIFT_KEY 

This keyword refers to VAXTPU’s shift key (by default PFl), not the key 
marked SHIFT on the keyboard. 

keyword 

A VAXTPU key name for a key. 

String 

A string that is a key map list name. This optional argument specifies 
the key map list in which the shift key is used. If the key map list is not 
specified, the key map list associated with the current buffer is used. 

DESCRIPTION 

The VAXTPU shift key is similar to the GOLD key in the EDT editor. This 
shift key allows you to assign two commands to one key: one is used when 
the key is pressed by itself, and the other is used when the key is pressed 
after the defined shift key. 

Only one VAXTPU shift key can be active at a time. The VAXTPU shift 
key can be any key other than the following: 

• The SHIFT key 

• The ESCAPE key 

• The SCROLL key on the VTl 00 keyboard 

• The FI, F2, F3, F4, and F5 keys on the VT300 or VT200 keyboard 

• The Compose Character key on the VT300 or VT200 keyboard 

By default, PFl is the VAXTPU shift key. 

You cannot make VAXTPU execute a procedure or learn sequence bound 
to the shift key. However, designating a defined key as the shift key does 
not undefine the key; it merely disables the definition so long as the key 
is designated as the shift key. If you define another key as the shift key, 
VAXTPU reenables the first key’s definition. 

If you want to use PFl for another purpose, use SET (SHIFT_KEY) to 
define a key other than PFl as VAXTPU’s shift key. 

If you use SET (SHIFT_KEY) to define a GOLD key in EVE, EVE does not 
undefine the GOLD key correctly. When you use the EVE command SET 
NOGOLD or SET NOSHIFT, EVE returns the error message "There is no 
user GOLD key currently set." Although this message appears to say that 
the GOLD key has successfully been undefined, what it really means is 
that EVE does not recognize that a GOLD key was ever defined. 
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To redefine a GOLD key in these circumstances, you can use either of the 
following approaches; 

• Use the EVE command SET GOLD KEY or SET SHIFT KEY. 

• Undefine the GOLD key using the VAXTPU statement 

SET (SHIFT_KEY, KEY_NAME (PFl, SHIFT_KEY)). Then set the 
GOLD key using the SET GOLD KEY or SET SHIFT KEY command. 


SIGNALED 

ERRORS 

TPU$_TOOFEW 

ERROR 

SET (SHIFT_KEY) requires at 
least two parameters. 


TPU$_TOOMANY 

ERROR 

You specified more than three 
parameters. 


TPUSJNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 


TPU$_BADKEY 

ERROR 

You specified an invalid keyword. 


TPU$_NOKEYMAPLIST 

WARNING 

You specified an undefined key 
map list. 


EXAMPLES 

Q SET (SHIFT_KEY, PF4, "tpu$lcey_map_list") 

This statement causes the keypad key PF4 to be defined as the shift 
key for the editor. The definition is stored in the default key map list, 
TPU$KEY_MAP_LIST. PF4 operates as the shift key only in buffers to 
which TPU$KEY_MAP_LIST is bound. 

I SET (SHIFT_KEY, KEY_NAME (PFl, SHIFT_KEY)) 

This statement disables the shift key by making the shift key itself a 
shifted key. Note that you can substitute the key name of whatever key 
is the SHIFT key. This technique works regardless of what key is defined 
as the SHIFT key. You might want to use such a statement if you are 
creating an editor that does not support user-defined shift key sequences. 
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SET (SPECIAL_ERROR_SYMBOL) 


FORMAT 

SET (SPECIAL_ERROR_SYMBOL, string) 

PARAMETERS 

SPECIAL_ERROR_SYMBOL 

A keyword specifying that you want to use SET to designate a global 
variable to be set to 0 when a case-style error handler does not return 
from a CTRL/C or other error. 

string 

The name of the global variable that you want VAXTPU to set to 0. 

DESCRIPTION 

Once you designate the variable that is to be the special error symbol, 
VAXTPU sets the variable to 0 if any of the following events occurs: 

• VAXTPU executes the TPU$_CONTROLC selector in a case-style error 
handler and does not encounter a RETURN statement 

• VAXTPU executes the OTHERWISE clause in a case-style error 
handler and does not encounter a RETURN statement 

• VAXTPU generates an error that is not handled by any clause in a 
case-style error handler 

You can only use SET (SPECIAL_ERROR_SYMBOL) once in a program. 
This built-in is usually used during initialization. You must declare or 
create the variable before you use it in the SET statement. VAXTPU does 
not clear the variable in response to non-case-style error handlers. 

The variable specified by SET (SPECIAL_ERROR_SYMBOL) can be used 
to determine whether VAXTPU has exited from current procedures and 
returned to the main loop to wait for a new keystroke. 

SIGNALED 

ERRORS 

TPU$_ERRSYMACTIVE ERROR A special error symbol has already 

been declared. 

TPU$_TOOFEW ERROR SET (SPECIAL_ERROR_ 

SYMBOL) requires two 
parameters. 

TPU$_TOOMANY ERROR You specified more than two 

parameters. 

TPU$JNVPARAM ERROR One or more of the specified 

parameters have the wrong type. 
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EXAMPLE 

SET (SPECIAL_ERROR_SYMBOL "back_to_main") 

This statement designates the global variable back_to_main as the 
variable to be cleared if a procedure or program with a case-style error 
handler fails to handle a CTRL/C error or other error. 
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SET (STATUS_LINE) 


FORMAT 


SET 


(STATUS_LINE, window, < 


NONE 

BOLD 

BLINK 

REVERSE 

SPECIAL_GRAPHICS 

UNDERLINE 


>, string) 


PARAMETERS STATUS_UNE 

The last line in a window. You can use the status line to display regular 
text or you can use it to display status information about the window. 

window 

The window whose status line you want to modify. 

NONE 

Applies no video attributes to the characters on the status line. 

BOLD 

Causes the characters on the status line to be bolded. 

BUNK 

Causes the characters on the status line to blink. 

REVERSE 

Causes the characters on the status line to be displayed in reverse video. 

SPECIAL_GRAPHICS 

Causes the characters on the status line to display graphic characters, 
such as a solid line. These characters are from the DEC Special Graphics 
Set (also known as the VTIOO Line Drawing Character Set). For more 
information on the special graphics that are available, see the appropriate 
programming manual for your video terminal. 

UNDERLINE 

Causes the characters on the status line to be underlined. 

string 

A quoted string, a variable name representing a string constant, or an 
expression that evaluates to a string, that is the text to be displayed on 
the status line. To remove a status line, use a null string (”") for this 
parameter. 


DESCRIPTION To have a status line, a window must be at least two lines high. You can 

establish a status line for a window when you create a window. CREATE_ 
WINDOW requires you to specify whether the status line is ON (used for 
status information) or OFF (used as a regular text line). When you specify 
ON, the default status line is displayed in reverse video. 
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The algorithm for determining whether a window is tall enough to be 
given a status line depends on whether the window is visible or invisible. 

If the window to which you want to add a status line is visible, VAXTPU 
checks the length of the visible portion of the window. A visible window 
can have an invisible portion if the window is partially occluded by another 
window. The visible portion of the visible window must have at least one 
text line; that is, at least one line not occupied by a scroll bar. 

If the window is invisible, VAXTPU checks the full length of the window. 
The window must have at least one text line. 

If the window that you use as a parameter for SET (STATUS_LINE) 
already has a status line, either because you specified ON for the status 
line parameter in the built-in procedure CREATE_WINDOW, or because 
you used a previous SET (STATUS^LINE) for the window, the video 
attribute that you specify is added to the video attribute of the existing 
status line unless you specify NONE. NONE overrides the other video 
keywords and specifies that there are to be no video attributes for the 
status line. The string you specify as the last parameter replaces the text 
of an existing status line. Adding a status line to a window that already 
has a status line does not cause an error. 

If there is no status line for a window, the built-in procedure SET 
(STATUS_LINE) establishes a status line on the last visible screen line 
of the window. The status line has the video attribute and the text you 
specify. Adding a status line reduces the number of screen lines available 
for text by one line. 

To remove a status line, use a null string ("") as the last parameter. The 
status line is removed even if the window is not two lines high at that 
time. 

The default setting for the status line (ON or OFF) is determined by the 
built-in procedure CREATE_WINDOW. 

If a window has a status line, by default the status line contains the 
name of the buffer associated with the window and the name of the file 
associated with the buffer, if there is one. 


SIGNALED 

ERRORS 

TPU$_TOOFEW 

ERROR 

SET (STATUS_LINE) requires four 
parameters. 


TPU$__TOOMANY 

ERROR 

You specified more than four 
parameters. 


TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 


TPU$_BADKEY 

ERROR 

The keyword must be NONE, 
BOLD, BLINK, REVERSE, 
UNDERLINE, or SPECIAL^ 
GRAPHICS. 


TPU$_UNKKEYWORD 

ERROR 

You specified an unknown 
keyword. 
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TPU$_STATOOLONG 

TPU$_BADWINDLEN 


INFO The status line is truncated to the 

screen width. 

ERROR The window must be at least two 
lines long. 


EXAMPLES 

D SET (STATUS_LINE, iny_window, REVERSE, "MAIN BUFFER, newfile.txt"); 

This statement displays the status line in myjvindow in reverse video 
with the buffer specified as MAIN BUFFER and the file specified as 
NEWFILE.TXT. 

g SET (STATUS_LINE, my_window, NONE, ; 

This statement removes the status line in my_window by setting the final 
parameter to a null string. 

s line_text := "qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq" + 
"qqqqqqqqqqqqqqqqqqqqq"; 

line_window := CREATE_WINDOW (1, 20, OFF); 

MAP (line_window, current_buffer)/ 

SET (STATUS_LINE, line_window, SPECIAL_GRAPHICS, line_text); 

This code fragment creates a window with a status line displayed 
in special graphics rendition. Since the glyph (member of the DEC 
Multinational Character Set occupying one column width) having the 
same value as the character "q" is a full-width line, the status line appears 
as a solid line across the screen. 
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SET (SUCCESS) 


FORMAT 

SET (SUCCESS, { }; 

PARAMETERS 

SUCCESS 

Controls whether VAXTPU writes success messages to the message buffer. 

ON 

Causes the success messages to be written. 

OFF 

Suppresses the display of success messages. 

DESCRIPTION 

By default, VAXTPU writes success messages to the message buffer. If you 
want to suppress the display of these messages, you can use this built-in 
procedure. 

See Appendix D for a table of the VAXTPU messages and their severity 
levels. 

SIGNALED 

ERRORS 

TPU$_TOOFEW ERROR SET (SUCCESS) requires two 

parameters. 

TPU$_TOOMANY ERROR You specified more than two 

parameters. 

TPU$_INVPARAM ERROR One or more of the specified 

parameters have the wrong type. 

TPU$_BADKEY ERROR You specified an invalid keyword. 

EXAMPLE 


SET (SUCCESS, OFF) 

This statement turns off the display of success messages. 
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SET (SYSTEM) 


FORMAT 

SET (SYSTEM, buffer) 

PARAMETERS 

SYSTEM 

The status of a buffer. SYSTEM means that it is a system buffer rather 
than a user buffer. 

By default, newly created buffers are user buffers. 

buffer 

The buffer that is being set as a system buffer. 

DESCRIPTION 

Once you make a buffer a system buffer, you cannot reset the buffer to be 
a user buffer. 

The SET (SYSTEM) built-in procedure allows programmers who are 
building an editing interface to distinguish their system buffers from 
buffers that the user creates. VAXTPU does not handle system buffers 
differently from user buffers. Any distinction between the two kinds of 
buffers must be implemented by the application programmer. 

SIGNALED 

ERRORS 

TPU$_TOOFEW ERROR SET (SYSTEM) requires two 

parameters. 

TPU$_TOOMANY ERROR You specified more than two 

parameters. 

TPU$JNVPARAM ERROR One or more of the specified 

parameters have the wrong type. 

TPU$__BADKEY ERROR You specified an invalid keyword. 


EXAMPLE 

SET (SYSTEM, message_buffer) 

This statement makes the message buffer a system buffer. 
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SET (TAB_STOPS) 

FORMAT 

SET (TAB_STOPS, buffer, | |) 

PARAMETERS 

TAB_STOPS 

A keyword indicating that SET is to control placement of tab stops in a 
buffer. 


buffer 

The buffer in which the tab stops are being set. 


integer 

An integer specifying the interval between tab stops, measured in column 
widths. The minimum value for the integer is 1. The maximum vedue is 
65,535. 


String 

A string of numbers that specifies the tab stops. The string represents 
column numbers at which the tab stops are placed. The minimum value 
for a tab stop is 1. The maximum value is 65,535. The maximum number 
of tab stops that you can include in the string is 100. The quoted string 
must list tab stops in ascending order, separating values with a single 
space: ("3 6 9 12.") 


DESCRIPTION When a buffer is created, the tabs are set at every eight columns, unless, 

when the buffer is created, a template buffer with different tab settings is 
specified. 

The SET (TAB_STOPS) built-in enables you to set the tab stops at 
positions you specify or to establish equal intervals other than the default 
eight. 

Tab stops are not saved when you write a file. When you create a buffer, 
the tabs are set to the default, unless, when you create the buffer, you 
specify a template buffer with different tab settings. 

SET (TAB_STOPS) does not affect the hardware tab settings of your 
terminal. On any terminals or printers that have tab settings different 
from those you specify with this built-in, the file does not appear the 
same as it does when viewed using VAXTPU. In addition, if you invoke 
VAXTPU with the /NODISPLAY qualifier, any values you enter for SET 
(TAB_STOPS) are ignored, and a SHOW (BUFFER) command will return 
tabs every 0 columns. 
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SET (TAB_STOPS) 


SIGNALED 

ERRORS 

TPU$_TOOFEW 

ERROR 

SET (TAB_STOPS) requires at 
least three parameters. 


TPU$_TOOMANY 

ERROR 

You specified more than three 
parameters. 


TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 


TPU$_UNKKEYWORD 

ERROR 

You specified an unknown 
keyword. 


TPU$_ARGMISMATCH 

ERROR 

The third parameter must be a 
string or an integer. 


TPU$JNVTABSPEC 

WARNING 

You specified a bad third 
argument. 


EXAMPLES 

Q SET (TAB_STOPS, CURRENT_BUFFER, 4); 


This statement causes the tab stops in the current buffer to be set at 
intervals of 4 columns. 

I SET (TAB_STOPS, CURRENT_BUFFER, "4 8 12 16"); 

This statement causes the tab stops in the current buffer to be set at 4, 8, 
12, and 16 columns. 
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SET (TEXT) 


FORMAT 

f widget, string 

1 ( BLANK TABS ) 1 , 

SET (ItXI, < \ GRAPHIC TABS > 

1 NO_TRANSLATE ) , 

PARAMETERS 

TEXT 

A keyword indicating that SET is to control the way text is displayed in a 
window or to determine the text that is to appear in a widget. 

widget 

The widget instance whose text you want to set. SET (TEXT, widget, 
string) is equivalent to the XUI Toolkit routine S TEXT SET STRING, 

You can only use widget as the second parameter if you are using 
DECwindows VAXTPU. 

string 

The text you want to assign to the simple text widget. 

window 

The window in which the mode of display is being set. 

BLANK_TABS 

Displays tabs as blank spaces. This is the default keyword. 

GRAPHIC_TABS 

Displays tabs as special graphic characters so that the width of each tab is 
visible. 

NO_TRANSLATE 

Sends every keystroke from the keyboard to the terminal without any 
translation. In this mode, the terminal settings, not VAXTPU, determine 
the effect of characters typed from the keyboard. 

Digital recommends that you use this mode for sending directives to 
the terminal but not for editing. VAXTPU does not manage margins or 
window shifts while NO_TRANSLATE mode is enabled. Furthermore, 
VAXTPU does not necessarily update lines of text in the order in which 
they appear while NO_TRANSLATE mode is enabled. 

To send escape sequences from within a VAXTPU procedure, you can use 
SET (TEXT) with the NO_TRANSLATE keyword followed by statements 
using the MESSAGE and UPDATE built-ins. See the example in this 
built-in description for more information on this technique. 

For more information on the effect of using various characters and 
sequences in NO_TRANSLATE mode, see your terminal manual. 
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SET (TEXT) 


SIGNALED 

ERRORS 


TPU$_BADKEY 

WARNING 

You specified an invalid keyword 
as a parameter. 

TPU$JNVPARAM 

ERROR 

One of the parameters was 
specified with data of the wrong 
type. 

TPU$_NORETURNVALUE 

ERROR 

SET (TEXT) cannot return a value. 

TPU$_REQUIRESDECW 

ERROR 

You have specified widget as the 
second parameter to SET (TEXT) 
while using non-DECwindows 
VAXTPU. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
SET (TEXT) built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the SET (TEXT) built-in. 

TPU$_WIDMISMATCH 

ERROR 

The specified widget is not of class 
SText. 

TPU$_UNKKEYWORD 

ERROR 

You specified an unknown 
keyword. 


EXAMPLES 

Q SET (TEXT, user_text_widget, "No default string available."); 

Assuming that the variable userJtextjjuidget has been assigned a text 
widget instance, this statement causes the widget to display the text No 
default string available, 

§ wildcard_dialog__box := GET_INFO (WIDGET, "widget_id", 

eve$x_wildcard__f ind_dialog, 

"WILDCARD_FIND_DIALOG.WILDCARD_FIND__TEXT"); 
status ;= SET (TEXT, wildcard_dialog_box, eve$x__target); 

These statements show one possible way that a layered application can 
use the SET (TEXT) widget. The variable eve$x_target stores the string 
(if one exists) that the user specified as the wildcard search string the 
last time the user invoked the wildcard find dialog box. The SET (TEXT) 
statement directs EVE’s wildcard find dialog box widget to display the 
string assigned to eve$xjarget, 

g SET (TEXT, CURRENT_WINDOW, GRAPHIC_TABS) 

This statement causes the text in the main window to be displayed with 
special characters indicating tab characters. 
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Q ! If your terminal has a printer hooked up to the printer port, 

! the following procedure allows you to perform a PRINT SCREEN 
! function. 

PROCEDURE user_print 

! Set window to NO_TRANSLATE to allow the escape sequence 
! to pass to the printer. Note that this procedure does not send 
! a form feed. 

SET (TEXT, message_window, NO__TRANSLATE) ; 

MESSAGE (ASCII (27) + "[i"); 

UPDATE (message_window)/ 

! Put back the window the way it was. 

SET (TEXT, message_window, BLANK_TABS); 

ERASE (message_buffer) ; 

ENDPROCEDURE; 


This procedure uses the NO_TRANSLATE keyword. Notice that the 
window is set to this state temporarily, and that the default setting for 
the window is reset as soon as the function for which NO_TRANSLATE is 
used is finished executing. 
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SET (TIMER) 


FORMAT 

SET (TIMER, { } [, String ]l) 

PARAMETERS 

TIMER 

Controls attributes of messages displayed in the prompt area. 

ON 

Causes the message that you specify to be written to the prompt area and 
displayed at 1-second intervals. By default, the timed message is turned 
on. 

OFF 

Turns off the display of timed messages in the prompt area. 

String 

A quoted string, a variable name representing a string constant, or an 
expression that evaluates to a string, that is displayed in the prompt area. 
The maximum length of the message is 15 characters. If you specify a 
string longer than 15 characters, VAXTPU truncates the string but does 
not signal an error. The message is displayed in the last 15 character 
positions of the prompt area. If ON is specified and a string was never 
specified for the last argument, the timer puts out the message “working”. 
If ON is specified and a string was specified previously, the saved string is 
used as the default. 

DESCRIPTION 

When SET (TIMER) is set to ON, the timer puts out messages at 1-second 
intervals while you are executing procedures or editing actions that are 
bound to a key. The message is written out to the prompt area and then 
erased to clear the prompt area for the next message. 

SIGNALED 

ERRORS 

TPU$_TOOFEW ERROR SET (TIMER) requires at least two 

parameters. 

TPU$_TOOMANY ERROR You specified more than three 

parameters. 

TPU$_INVPARAM ERROR One or more of the specified 

parameters have the wrong type. 

TPU$_BADKEY error The keyword must be ON or OFF. 

TPU$_UNKKEYWORD ERROR You specified an unknown 

keyword. 
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SET (TIMER) 


EXAMPLE 

SET (TIMER, ON, 


"Executing") 

This statement causes the message "Executing" to be written to the prompt 
area at 1-second intervals while you are executing a VAXTPU procedure. 
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SET (TRACEBACK) 


FORMAT 

SET (TRACEBACK, { 

PARAMETERS 

TRACEBACK 

Whether VAXTPU displays the sequence of procedures called after an 
error occurs. 

ON 

Causes VAXTPU to display the procedure calling sequence after an error 
occurs. 

OFF 

Prevents VAXTPU from displaying the procedure calling sequence after an 
error occurs. 

DESCRIPTION 

Traceback information provides the context in which an error occurs. 
Turning on the traceback setting can be helpful to a programmer 
debugging a VAXTPU program. The traceback setting is usually turned off 
during normal editing, because end users of editors do not usually use the 
traceback information. 

The default setting for TRACEBACK depends on whether a section file 
was loaded by VAXTPU. If a section file was loaded, the default is OFF. If 
a section file was not loaded, the default is ON. 

Note that SET (TRACEBACK) is related to SET (LINE.NUMBER). SET 
(TRACEBACK, ON) turns on both traceback and line numbers because 
both are needed for debugging. SET (LINE_NUMBER, OFF) turns off 
both traceback and line numbers because one feature is not useful without 
the other. 

Allowable settings are as follows: 

• Both off 

• Both on 

• Traceback off 

• Line number on 

SIGNALED 

ERRORS 

TPU$_TOOFEW ERROR The SET (TRACEBACK) built-in 

requires two parameters. 

TPU$_TOOMANY ERROR You specified more than two 

parameters. 
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TPU$_INVPARAM 

TPU$_BADKEY 


ERROR One or more of the specified 

parameters have the wrong type. 

WARNING Only ON and OFF are allowed. 


EXAMPLES 

Q SET (TRACEBACK, OFF) 

This statement prevents VAXTPU from displaying the procedure calling 
sequence after an error occurs. 


PROCEDURE traceback_example 
SET (TRACEBACK, ON)/ 

SET (TRACEBACK, BELL); 
RETURN 5; 

ENDPROCEDURE; 


PROCEDURE call_example 
traceback_example; 

ENDPROCEDURE; 

This procedure results in a traceback display when the procedure is 
executed and traceback is enabled. 

Invoking the procedure CALL_EXAMPLE results in the following 
traceback: 


BELL is an invalid keyword 
Occurred in builtin SET 
At line 2 

Called from builtin EXECUTE 

Called from line 22 of procedure EVE_TPU 

Called from line 1 

Called from builtin EXECUTE 

Called from line 96 of procedure EVE$PROCESS_COMMAND 
Called from line 3 of procedure EVE$PARSER_DISPATCH 
Called from line 97 of procedure EVE$$EXIT_COMMAND_WINDOW 

Called from line 2 


7-489 








VAXTPU Built-In Procedures 

SET (UNDEFINED_KEY) 


SET (UNDEFINED_KEY) 


' buffer 'j 

learn_sequence 
, < program > ) 

range 

. string2 J J 


FORMAT 


SET (UNDEFINED_KEY, stringl 


PARAMETERS UNDEFINED_KEY 

A ke3rword specifying that SET is to determine the action taken when an 
undefined key is input. 

Stringl 

A string specifying the key map list for which this procedure is called. 

buffer 

The buffer containing VAXTPU statements specifying the action to be 
taken if the user presses an undefined key. SET (UNDEFINED_KEY) 
compiles the statements in the buffer and stores the resulting program in 
the specified key map list. 

Iearn_sequence 

The learn sequence specifying the action to be taken if the user presses 
an undefined key. The contents of a variable of type learn do not require 
compilation. SET (UNDEFINED_KEY) stores the learn sequence in the 
specified key map list. 

program 

The program specifying the action to be taken if the user presses an 
undefined key. The contents of a variable of type program do not require 
compilation. SET (UNDEFINED_KEY) stores the program in the specified 
key map list. 

range 

The range containing VAXTPU statements specifying the action to be 
taken if the user presses an undefined key. SET (UNDEFINED_KEY) 
compiles the statements in the range and stores the resulting program in 
the specified key map list. 

strmg2 

The string containing VAXTPU statements specifying the action to be 
taken if the user presses an undefined key. SET (UNDEFINED_KEY) 
compiles the statements in the string and stores the resulting program in 
the specified key map list. 


Qg0QP|py|0^ SET (UNDEFINED_KEY) determines the action taken when an undefined 

key is pressed. 

If the third parameter is not specified, VAXTPU displays the message "key 
has no definition" when the user presses an undefined key. 
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SET (UNDEFINED_KEY) 


SIGNALED 

ERRORS 

TPU$_NOKEYMAPLIST 

WARNING 

You attempted to access an 
undefined key map list. 


TPU$_TOOFEW 

ERROR 

SET (UNDEFINED_KEY) requires 
at least two parameters. 


TPU$_TOOMANY 

ERROR 

SET (UNDEFINED_KEY) accepts 
no more than three parameters. 


TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 


TPU$_ARGMISMATCH 

ERROR 

The second parameter must be a 
string. 


EXAMPLE 

IF GET_INFO ("tpu$key_map_list", "undefined_key") <> 0 
THEN 

SET (UNDEFINED_KEY, "tpu$key_map_list"); 

ENDIF; 


This code causes the default undefined key message to be displayed when 
an undefined key is entered. 
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SET (VIDEO) 


FORMAT 

( NONE ) 

BOLD 

SET (VIDEO, window, < BLINK 

REVERSE 

1 UNDERLINE i 

PARAMETERS 

VIDEO 

The video attributes of a window. 

window 

The window in which a video attribute is being set. 

NONE 

Applies no video attributes to the characters in the window. This is the 
default. 

BOLD 

Causes the characters in the window to be bolded. 

BUNK 

Causes the characters in the window to blink. 

REVERSE 

Causes the characters in the window to be displayed in reverse video. 

UNDERLINE 

Causes the characters in the window to be underlined. 

DESCRIPTION 

Video attributes for a window are cumulative. The window assumes the 
video attribute of each video keyword that you use with SET (VIDEO) 
during an editing session. If you want to change the video attribute of a 
window, and you do not want the cumulative effect of previous attributes, 
use SET (VIDEO, window, NONE) before specif 3 dng the new attribute. 
SET (VIDEO, window, NONE) turns off all video attributes for a window. 

The video attribute is applied during the next screen update. The screen 
manager repaints the window to apply the video attributes, even if the 
cumulative effect of your changes has been to leave the video attributes 
the same. 

Note that the built-in procedure SET (VIDEO) does not affect the status 
line of a window. You can specify a video attribute for a status line 
either with CREATE_WINDOW or with the built-in procedure SET 
(STATUS_LINE). When the window and the status line have different 
video attributes, the status line can be used to separate multiple windows 
on the screen, or to highlight status information. 
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SET (VIDEO) 


SIGNALED 

ERRORS 

TPU$_TOOFEW 

ERROR 

SET (VIDEO) requires three 
parameters. 


TPU$_TOOMANY 

ERROR 

SET (VIDEO) accepts no more 
than three parameters. 


TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 


TPU$_BADKEY 

ERROR 

You specified an invalid keyword. 


TPU$_UNKKEYWORD 

ERROR 

You specified an unknown 
keyword. 


EXAMPLE 

SET (VIDEO, CURRENT_WINDOW, REVERSE); 

SET (VIDEO, CURRENT_WINDOW, UNDERLINE); 

These statements cause the current window to be displayed in reverse 
video and with underlining. 
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SET (WIDGET) 



Allows you to assign values to various resources of a widget. 

FORMAT 

SET (WIDGET, widget, 

{ widget_args [, widget_args... | } j 

PARAMETERS 

WIDGET 

A keyword directing VAXTPU to set an attribute of a widget. 

widget 

The widget instance whose values you want to set. 

widget_args 

One or more pairs of resource names and resource values. You can 
specify a pair in an array or as a pair of separate parameters. If you 
use an array, you index the array with a string that is the name of the 
resource you want to set. Note that resource names are case sensitive. 

The corresponding array element contains the value you want to assign to 
that resource. The array can contain any number of elements. If you use 
a pair of separate parameters, use the following format: 

resource_name_string, resource_value 

Arrays and string/value pairs may be interspersed. Each array index 
and its corresponding element value, or each string and its corresponding 
value, must be valid widget arguments for the class of widget whose 
resources you are setting. 

DESCRIPTION 

This built-in is functionally equivalent to the X Toolkit routine SET 
VALUES. 

If you specify the name of a resource that the widget does not support, 
VAXTPU signals the error TPU$_ARGMISMATCH. 

For more information about specifying resources, see Chapter 4. 

SIGNALED 

ERRORS 

TPU$_BADKEY WARNING You specified an invalid keyword 

as a parameter. 

TPU$_ARGMISMATCH ERROR You specified a vaiue whose data 

type is not supported. 

TPU$_NONAMES WARNING You specified an invalid widget 

resource name. 

TPU$_NORETURNVALUE ERROR SET (WIDGET) cannot return a 

value. 


7-494 











VAXTPU Built-In Procedures 

SET (WIDGET) 


TPU$_REQUIRESDECW 

ERROR 

You can use the SET (WIDGET) 
built-in only if you are using 
DECwindows VAXTPU. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
SET (WIDGET) built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the SET (WIDGET) built-in. 

TPU$_WIDMISMATCH 

ERROR 

You have specified a widget whose 
ciass is not supported. 


EXAMPLE 

scroll_bar_widget := SET (SCROLL_BAR, CURRENT_WINDOW, VERTICAL, ON); 

SET (WIDGET, scroll_bar_widget, eve$dwt$c_nvalue, 100); 

These statements set the Nvalue resource of the current window’s scroll 
bar widget to 100. This causes the scroll bar slider to be displayed as far 
toward the bottom of the scroll bar widget as possible. 

For an example of a procedure using the SET (WIDGET) built-in, see 
Example B-8. 
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SET (WIDGET_CALL_DATA) 



Allows you to create a template telling VAXTPU how to interpret the 
information in the fields of a widget’s callback data structure. 

FORMAT 

SET (WIDGET_CALL_DATA, widget, reason_code, request_string, keyword 
[, requestjstring, keyword...]) 

PARAMETERS 

WIDGET_CALL_DATA 

A keyword indicating that the SET built-in is being used to control how 
VAXTPU interprets information in a widget’s callback data structure. 

widget 

The specific widget instance for which you want to determine how the 
callback data are interpreted. 

reasonjcode 

The identifier for the reason code with which the callback data structure 
is associated. For example, if you are using SET (WIDGET_CALL_DATA) 
to set the format of the callback structure associated with the Help 
Requested reason code of the File Selection widget and if your program 
defines the VAX reason code bindings as constants, you could refer to the 
Help Requested reason code by using the constant DWT$C_CRHELP_ 
REQUESTED. 

request_string 

One of the six valid strings describing the data type of a given field in a 
callback data structure. The valid strings are as follows: 

"char" "compound_string" 

"int" "short" 

"void" "widget" 

keyword 

One of the four valid keywords indicating the VAXTPU data type to 
which VAXTPU should convert the data in a given field of a callback data 
structure. The valid keywords are as follows: 

INTEGER STRING 

UNSPECIFIED WIDGET 

Use the requestjstring parameter with the keyword parameter to inform 
VAXTPU, for each field of the structure, what data type the field had 
originally and what VAXTPU data type corresponds to the original data 
type. The valid keywords corresponding to each request string are as 
follows: 
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DESCRIPTION 


Request string 

Associated keyword(s) 

"widget" 

WIDGET or UNSPECIFIED 

"short" 

INTEGER or UNSPECIFIED 

"int" 

INTEGER or UNSPECIFIED 

"compound_string" 

STRING or UNSPECIFIED 

"char" 

STRING or UNSPECIFIED 

"void" 

UNSPECIFIED 


You use SET (WIDGET_CALL_DATA) to tell VAXTPU what data type to 
assign to each field in a callback data structure. You must specify the 
widget and the callback reason whose data structure you want VAXTPU 
to process. During a callback generated by the specified widget for the 
specified reason, VAXTPU interprets the data in the callback structure 
according to the description you create. 

In an application layered on VAXTPU, you can obtain the interpreted 
callback data by using the built-in GETJNFO (WIDGET, "callback,, 
parameters"). 

You can create a different template for each of the reason codes associated 
with a given widget. To do so, make a separate call to the SET (WIDGET_ 
CALL_DATA) built-in for each reason code. If you specify the same widget 
and reason code in more than one call, VAXTPU uses the most recently 
specified format. 

In all callback data structures defined by the DECwindows Toolkit, the 
first field is the reason code field and the second field is the event field. 
For more information on the fields in each widget’s callback structures, 
see the VMS DECwindows Toolkit Routines Reference Manual. If your 
application creates or uses a new kind of widget, the widget’s callback 
structure must follow this convention. 

Do not specify any request string or keyword for the reason field. In 
almost all cases, you specify the event field with the request string "void" 
and the keyword UNSPECIFIED. Specify all subsequent fields, if the 
callback structure has such fields, up to and including the last field you 
want to specify. Note that the VAX longword data type corresponds to the 
"int" request string and the INTEGER data type in VAXTPU. 

Although you can skip trailing fields, you cannot skip intermediate fields 
even if they are unimportant to your application. To direct VAXTPU to 
ignore the information in a given field, use the request string "void" and 
the keyword UNSPECIFIED when specifying that field. 

If you specify an invalid request string, VAXTPU signals TPU$_ 
ILLREQUEST. If you specify an invalid keyword, VAXTPU signals TPU$_ 
BADKEY. If you use valid parameters but assign the wrong data type to 
a field and if VAXTPU detects the error, VAXTPU assigns the data type 
UNSPECIFIED to that field during processing of a callback. 
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An application should use this built-in only if it needs access to callback 
information other than the reason code. For more information on how 
SET (WIDGET_CALL_DATA) affects GETJNFO (WIDGET, "callback, 
parameters"), see the online HELP topic GET_INFO(WIDGET). 


SIGNALED 

ERRORS 


TPU$_BADKEY 

WARNING 

You specified an invalid keyword 
as a parameter. 

TPU$_NORETURNVALUE 

ERROR 

Built-in does not return a value. 

TPU$_REQU1RESDECW 

ERROR 

You can use this built-in only if you 
are using DECwindows VAXTPU. 

TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to 
the SET (WIDGET-CALL_DATA) 
built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the SET (WIDGET-CALL^DATA) 
built-in. 


EXAMPLE 


CONSTANT DWT$C_CRSINGLE := 20; 

SET (WIDGET_CALL_DATA, initial_list_box, DWT$C_CRSINGLE, 
"void", UNSPECIFIED, ! event 

"compound.string", STRING, ! item 

"int", INTEGER, ! item length 

"int", INTEGER); ! item number 


This code fragment begins by defining the constant DWrr$C_ 

CRSINGLE to be the integer value 20, which is the integer associated 
with the reason "user selected a single item." Note that the file 
SYS$LIBRARY:DECW$DWTSTRUCT.H contains constants defined for 
reason code. If you layer an application, the vedues you assign to the 
reason code constants must match the values in this file. The next 
statement tells VAXTPU how to interpret the fields of the callback data 
structure associated with a List Box widget assigned to the variable 
"initial_list_box". The statement directs VAXTPU to ignore the data in the 
"event" field and to treat the data in the item field as type STRING, in the 
"item length" field as type INTEGER, and the "item number" field as type 
INTEGER. 
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SET (WIDGET_CALLBACK) 



Specifies the VAXTPU program or learn sequence to be called by VAXTPU 
when a widget callback occurs for the widget instance. 

FORMAT 

' buffer \ 

learn_sequence 

SET (WIDGET_CALLBACK, widget, < program y closure) 

range 

, string ) 

PARAMETERS 

WIDGET_CALLBACK 

A keyword directing VAXTPU to set the application-level widget callback. 

widget 

The widget instance whose callback you want to set. 

buffer 

The buffer that contains the application-level callback routine. This code 
is executed when the widget performs a callback to VAXTPU. 

Iearn_sequence 

The learn sequence that specifies the application-level callback routine. 
This code is executed when the widget performs a callback to VAXTPU. 

program 

The program that specifies the application-level callback routine. This 
code is executed when the widget performs a callback to VAXTPU. 

range 

The range that contains the application-level callback routine. This code 
is executed when the widget performs a callback to VAXTPU. 

string 

The string that contains the application-level callback routine. This code 
is executed when the widget performs a callback to VAXTPU. 

ciosure 

A string or integer. VAXTPU passes the value to the application when 
the widget performs a callback to VAXTPU. Note that DECwindows 
documentation refers to closures as tags. For more information about 
using closures, see Chapter 4. 
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SIGNALED 

ERRORS 


TPU$_ARGMISMATCH 

ERROR 

The data type of the indicated 
parameter is not supported by 
the SET (WIDGET_CALLBACK) 
built-in. 

TPU$_BADDELETE 

ERROR 

You are attempting to modify an 
integer, a keyword, or a string 
constant. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to 
the SET (WIDGET_CALLBACK) 
built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the SET (WIDGET_CALLBACK) 
built-in. 

TPU$_C0MPILEFA1L 

WARNING 

Program compilation has been 
terminated because of a syntax 
error. 

TPU$_REQUIRESDECW 

ERROR 

You can use SET (WIDGET^ 
CALLBACK) only if you are usini 
DECwindows VAXTPU. 


EXAMPLE 

SET (WIDGET_CALLBACK, scroll_bar_widget, "eve$scroll_dispatch", 'h'); 

This statement designates the EVE procedure EVE$SCROLL_DISPATCH 
as the callback routine for the widget scrolljbar_widget and assigns to the 
callback the closure value ’h’. 

For a procedure using this statement to map windows see Example B—7. 


7-500 






VAXTPU Built-In Procedures 

SET (WIDTH) 


SET (WIDTH) 



Sets the width of a window or the VAXTPU screen. 

FORMAT 

f window ) 

SET (WIDTH, \ ALL integer) 

I SCREEN ) 

PARAMETERS 

WIDTH 

A ke3rword indicating that the horizontal dimension is being set. 

window 

The window for which you want to set or change the width. 

ALL 

A keyword indicating that VAXTPU should set the screen and all windows, 
visible and invisible, to the specified width. 

SCREEN 

A keyword indicating that VAXTPU should set the screen to the specified 
width without altering the size of any VAXTPU windows. Note, however, 
that by default EVE resizes the windows to match the width of the screen. 
Note, too, that you cannot set the screen to be narrower than the widest 
VAXTPU window. 

integer 

The width of the window in columns. You can specify any integer between 
1 and 255. In non-DECwindows VAXTPU, a value of 80 causes VAXTPU 
to repaint the screen and depict the text in normal-width font, if the text 
is not already so depicted. A value of 132 causes VAXTPU to repaint 
the screen and depict the text in narrow font, if the text is not sdready 
so depicted. Other values do not siffect the font. By default, the width 
of a window is the same as the physical width of the terminal when the 
window is created. 

DESCRIPTION 

When you call SET (WIDTH), VAXTPU determines the width of the widest 
visible window. If this width has changed, the effect of SET (WIDTH) 
depends on your terminal. 

If you are using VAXTPU with a VWS or DECwindows terminal emulator, 
the terminal emulator is resized to match the width of the widest visible 
window. You can specify any width between 1 column and 255 columns. 

If you are using VAXTPU on a VT300-series, VT200-series, or VTlOO-series 
terminal, setting the width of a window only causes a change if the widest 
visible window is 80 or 132 columns wide. When the new width is one of 
these numbers, VAXTPU causes the terminal to switch from 80-column 
mode to 132-column mode, or the reverse. 
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If you are using DECwindows VAXTPU (that is, not in a DECterm 
window), changing the width of the screen does not affect the font of 
the characters displayed. (There are no 80-column or 132-column modes.) 

If the width of the widest visible window has changed, VAXTPU redisplays 
all windows. 

By default, the width of a window is the same as the number of columns 
on the screen of the terminal on which you are running VAXTPU. If you 
exceed the value set for the width of the window when entering text, 
VAXTPU displays a diamond S 3 mibol in the rightmost column of the screen 
to indicate that there is text beyond the diamond symbol that is not visible 
on the screen. You cannot force VAXTPU to use multiple lines to display a 
line that is longer than the width of a window. 


SIGNALED 

ERRORS 

TPU$_TOOFEW 

ERROR 

SET (WIDTH) requires three 
parameters. 


TPU$_TOOMANY 

ERROR 

You specified more than three 
parameters. 


TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 


TPU$_BADVALUE 

ERROR 

Arguments are out of minimum or 
maximum bounds. 


EXAMPLES 

D SET (WIDTH, main_window, 132); 

This statement sets the width of the main window to 132 columns and 
changes the font from standard to narrow. 

g SET (WIDTH, ALL, 40); 

This statement sets the width of the screen and all windows, visible and 
invisible, to 40 columns. The statement does not affect the font. 
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SHIFT 

For a buffer whose lines are too long to be displayed ail at once, moves the 
window so the unseen parts of the lines can be viewed. SHIFT can move the 
window right to display text past the right edge of the window, or left (for a 
previously shifted window). SHIFT optionally returns an integer specifying the 
number of columns in the buffer lying to the left of the left edge of the shifted 
window. 

FORMAT 

[integer2 := ] SHIFT (window, integerl) 

PARAMETERS 

window 

The window that is shifted. 

integerl 

The signed integer that specifies how many columns to shift the window. 

A positive integer causes the window to shift to the right so that you can 
see text that was previously beyond the right edge of the window. 

A negative integer causes the window to shift to the left so that you can 
see text that was previously beyond the left edge of the window. If the first 
character in the line of text is already in column 1, then using a negative 
integer has no effect. 

If you specify 0 as the value, no shift takes place. Furthermore, 0 as the 
value does not cause the window to be repainted. 

By default, windows are not shifted. 

return value 

An integer representing the amount by which the window has been shifted 
to the right. 

DESCRIPTION 

Use the built-in procedure SHIFT when one or more lines of text in a 
buffer are too long to fit in the window (indicated by the diamond symbol 
in the rightmost column). By shifting the window from left to right, you 
can view text that was beyond the right edge of the window. 

Because SHIFT commands are cumulative during an editing session, this 
built-in procedure optionally returns a value in integer2. This positive 
integer represents the absolute shift value. 

The shift applies to any buffer associated with the window that you 
specify. For example, if you shift a window and then map another buffer 
to that window, you see the text of the newly mapped buffer in the shifted 
position. You must specify another shift to return the window to its 
unshifted position. 
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If you specify an integer value of 0, the window is not left-shifted. 
Furthermore, when you attempt to left-shift, the window is not repainted. 
Otherwise, SHIFT causes the entire window to be repainted. If you 
execute the built-in procedure SHIFT within a procedure, the screen is 
not updated to reflect the shift until the procedure has flnished executing 
and control has returned to the screen manager. If you want the screen 
to reflect changes before the entire program is executed, you can force the 
immediate update of a window by adding an UPDATE statement to the 
procedure. 


SIGNALED 

ERRORS 


TPU$_TOOFEW 

ERROR 

SHIFT requires two parameters. 

TPU$_TOOMANY 

ERROR 

You specified more than two 
parameters. 

TPU$JNVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 


EXAMPLES 

Q SHIFT (user_window, +5) 

This statement shifts the window userjuuindow flve columns to the right. 

g SHIFT (CURRENT_WINDOW, -5) 

This statement shifts the current window flve columns to the left. (If the 
window was not previously shifted, this statement has no effect.) 

g SHIFT (CURRENT_WINDOW, -SHIFT (CURRENT___WINDOW, 0)) 

This statement always returns the current window to an unshifted state. 


\ 
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SHOW 


Displays information about VAXTPU data types and the current settings of 
attributes that can be applied to certain data types. See also the description 
of the built-in procedure GETJNFO. 


FORMAT 


SHOW 


BUFFER[S] 
KEY_MAP_LIST[S] 
KEY_MAP[S] 
KEYWORDS 
PROCEDURES 
SCREEN 
SUMMARY 
VARIABLES 
WINDOW[S] 
buffer 
string 
. window 


PARAMETERS BUFFERgS ] 

Displays information about all buffers available to the editor. BUFFER is 
a synonym for BUFFERS. 

KEY_MAP_USTiS]l 

Displays the names of all defined key map lists, their key maps, and the 
number of keys defined in each key map. KEY_MAP_LIST is a synonym 
for KEY^MAP^LISTS. 

KEY_MAP[S]I 

Displays the names of all defined key maps. KEY_MAP is a synonjma for 
KEY_MAPS. 

KEYWORDS 

Displays the contents of the internal keyword table. 

PROCEDURES 

Displays the names of all defined procedures. 

SCREEN 

Displays information about the terminal. 

SUMMARY 

Displays statistics about VAXTPU, including the current version number. 

VARIABLES 

Displays the names of all defined variables. 

WINDOWfS j 

Displays information about all windows available to the editor. WINDOW 
is a synonym for WINDOWS. 
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buffer 

Shows information about the buffer variable you specify. 

String 

Shows information about the string variable you specify. 

window 

Shows information about the window variable you specify. 


DESCRIPTION VAXTPU looks for the variable showjbuffer and checks to see if it refers 

to a buffer. VAXTPU also looks for the variable infojuuindow and checks 
to see if it refers to a window. If these two items exist when you call the 
built-in procedure SHOW, VAXTPU writes information to showjbuffer and 
displays the information on the screen in the window called infojwindow. 

You, or the interface you are using, must create the buffer variable 
showjbuffer when you initialize the interface to ensure that the built-in 
procedure SHOW works as expected. 

If you create a window called infojwindoWy VAXTPU associates show_ 
buffer with infojwindow and maps this window to the screen when there 
is information to be displayed. You can optionally create a different 
window in which to display the information from showjbuffer. In this 
case, you must associate showjbuffer with the window that you create and 
map the window to the screen when there is information to be displayed. 

Because this built-in procedure maps INFOJWINDOW to the screen, any 
interfaces layered on VAXTPU should provide a mechanism for unmapping 
INFOjWINDOW and returning the user to the editing position that was 
current before the built-in procedure SHOW was invoked. 

VAXTPU always deletes the current text in the show buffer before 
inserting the new information. 


SIGNALED 

ERRORS 


TPU$_NOSHOWBUF 

WARNING 

The requested information cannot 
be stored because the buffer 



variable showjbuffer does not 



exist. 

TPU$_TOOMANY 

ERROR 

SHOW accepts only one 
parameter. 

TPU$_INVPARAM 

ERROR 

One or more of the specified 
parameters have the wrong type. 


EXAMPLES 

Q SHOW (PROCEDURES) 

This statement displays on the screen a list of all the VAXTPU built-in 
procedures and the user-written procedures that are available to your 
editing interface. 
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g SHOW (KEY_MAP_LISTS) 


This statement displays the names of all defined key map lists, their key 
maps, and the number of keys defined in each key map. When you use the 
default interface, EVE, the VAXTPU command SHOW (KEY_MAP_LISTS) 
displays information similar to the following: 

Defined key map lists: 


TPU$KEY_MAP_LIST contains the following key maps: 


EVE$USER_KEYS 
EVE$VT200_KEYS 
EVE$STANDARD KEYS 


(0 keys defined) 
(14 keys defined) 
(29 keys defined) 


Total of 1 key map list defined 
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SLEEP 

Causes VAXTPU to pause for the amount of time you specify or until input is 
available. 

FORMAT 


PARAMETERS 

integer 

The number of seconds to sleep. 

String 

An absolute or a delta time string indicating how long to sleep. See the 
documentation on the system service $BINTIM for the format of this 
string. 

DESCRIPTION 

This built-in suspends VAXTPU for the specified amovmt of time. This 
built-in is useful if you wish to display something for only a short period 
of time. SLEEP ends immediately when input becomes available from the 
terminal. 

SIGNALED 

ERRORS 

TPU$_TOOFEW ERROR SLEEP requires one argument. 

TPU$_TOOMANY ERROR SLEEP accepts only one 

argument. 

TPU$_ARGMISMATCH ERROR The argument to SLEEP must be 

an integer or string. 

TPU$JNVTIME ERROR The argument to SLEEP was an 

invalid sleep time. 


EXAMPLES 

D SLEEP (2); 

This statement suspends VAXTPU for two seconds, 
g SLEEP ("0 0:0:1.50"); 

This statement suspends VAXTPU for one and one-half seconds. 
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§ PROCEDURE user___emphasize_message (user_message) 

LOCAL here, 

start_mark, 

the_range; 

here := MARK (NONE); 

POSITION (END_OF (message_buffer)) ; 

COPY_TEXT (user_message); 

MOVE_HORIZONTAL (-CURRENT_OFFSET); 
start_mark := MARK (NONE); 

MOVE_VERTICAL (1); 

MOVE_HORIZONTAL (-1); 

the_range := CREATE_RANGE (start_mark, MARK (NONE), REVERSE); 
UPDATE (message_window); 

SLEEP ("0 00:00:00.33”); 
the_range := 0; 

UPDATE (message_window); 

POSITION (here); 

ENDPROCEDURE; 


This procedure takes a string and puts it into the message buffer. The 
procedure displays the string in reverse video rendition for a third of a 
second. After a third of a second, the reverse video rendition is canceled 
and the string is displayed in ordinary rendition. 
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SPAN 

Returns a pattern that matches a string of characters, each of which appears 
in the buffer, range, or string used as its parameter. SPAN matches as many 
characters as possible. 

FORMAT 

pattern := SPAN ^ | | f. { Reverse } 

PARAMETERS 

buffer 

An expression that evaluates to a buffer. SPAN matches only those 
characters that appear in the buffer. 

range 

An expression that evaluates to a range. SPAN matches only those 
characters that appear in the range. 

string 

An expression that evaluates to a string. SPAN matches only those 
characters that appear in the string. 

FORWARD 

A keyword directing VAXTPU to match characters in the forward direction. 
This is the default. 

REVERSE 

A keyword directing VAXTPU to match characters as follows: first, match 
characters in the forward direction until VAXTPU finds a character that 
is not a member of the set of characters in the specified buffer, range, or 
string. Next, return to the first character matched and start matching 
characters in the reverse direction until VAXTPU finds a character that is 
not in the specified buffer, range, or string. 

You can specify REVERSE only if you are using SPAN in the first 
element of a pattern being used in a reverse search. In all other contexts, 
specifying REVERSE has no effect. 

The behavior enabled by REVERSE allows an alternate form of reverse 
search. By default, a reverse search stops as soon as a successful match 
occurs, even if there might have been a longer successful match in the 
reverse direction. By specifying REVERSE, you direct VAXTPU not to stop 
matching in either Erection until it has matched as many characters as 
possible. 

return value 

A pattern that matches a sequence of characters, each of which appears in 
the buffer, range, or string used in the parameter to SPAN. 
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DESCRIPTION SPAN matches one or more characters, each of which must appear in the 

string, buffer, or range passed as its parameter. SPAN matches as many 
characters as possible, stopping only if it finds a character not present in 



its parameter or if it reaches the end of a line. If SPAN is part of a larger 
pattern, SPAN does not match a character if doing so prevents the rest of 
the pattern from matching. 


SPAN does not cross line boundaries. To match a string of characters that 
may cross one or more line boundaries, use SPANL. 

SIGNALED 

ERRORS 

TPU$_NEEDT0ASS1GN 

ERROR 

SPAN must appear in the right- 
hand side of an assignment 
statement. 


TPU$_TOOFEW 

ERROR 

SPAN requires at least one 
argument. 


TPU$_TOOMANY 

ERROR 

SPAN accepts no more than one 
argument. 


TPU$_ARGMISMATCH 

ERROR 

Argument passed to SPAN is of 
the wrong type. 


TPU$_CONTROLC 

ERROR 

You pressed CTRLyC during the 
execution of SPAN. 


EXAMPLES 

D patl := SPAN ("0123456789”) 

This assignment statement creates a pattern that matches any sequence 
of numbers. 

§ patl := span ("abcdefghijklmnopqrstuvwxyz") + "s"; 


This assignment statement creates a pattern that matches any word of 
two or more letters ending in the letter s. Given the word dogs, the SPAN 
part of the pattern matches dog. It does not match the s as well as this 
would prevent the rest of the pattern from matching. 

PROCEDURE user_remove_xyz 

LOCAL patl^ 

xyz_line; 

patl := LINE_BEGIN + SPAN ("xyz") + LINE_END; 

LOOP 

xyz_line := SEARCH_QUIETLY (patl, FORWARD); 

EXITIF xyz_line = 0; 

POSITION (xyz_line); 

ERASE_LINE; 

ENDLOOP; 

ENDPROCEDURE; 


This procedure removes all lines that contain only the letters y, and z. 
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SPANL 

Returns a pattern that matches a string of characters and line breaks, each 
of which appears in the buffer, range, or string used as its parameter. The 
pattern matches as many characters and line breaks as possible. 

FORMAT 

pa«ern := SPANL ({«£)/■{ } » 

PARAMETER 

buffer 

An expression that evaluates to a buffer. SPANL matches only those 
characters that appear in the buffer. 

range 

An expression that evaluates to a range. SPANL matches only those 
characters that appear in the range. 

String 

An expression that evaluates to a string. SPANL matches only those 
characters that appear in the string. 

FORWARD 

A keyword directing VAXTPU to match characters in the forward direction. 
This is the default. 

REVERSE 

A keyword directing VAXTPU to match characters as follows: first, match 
characters in the forward direction until VAXTPU finds a character that 
is not a member of the set of characters in the specified bioffer, range, or 
string. Next, return to the first character matched and start matching 
characters in the reverse direction imtil VAXTPU finds a character that is 
not in the specified buffer, range, or string. 

You can specify REVERSE only if you are using SPANL in the first 
element of a pattern being used in a reverse search. In all other contexts, 
specifying REVERSE has no effect. 

The behavior enabled by REVERSE allows an alternate form of reverse 
search. By default, a reverse search stops as soon as a successful match 
occurs, even if there might have been a longer successful match in the 
reverse direction. By specifying REVERSE, you direct VAXTPU not to stop 
matching in either direction until it has matched as many characters as 
possible. 

return value 

A pattern matching a sequence of characters and line breaks. 
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DESCRIPTION SPANL is similar to SPAN in that it matches one or more characters, each 

of which must appear in the string, buffer, or range used as a parameter. 
However, unlike SPAN, SPANL does not stop matching when it reaches 
the end of a line. It successfully matches the end of the line and continues 
trying to match characters on the next line. If SPANL is part of a larger 
pattern, it does not match a character or line boundary if doing so prevents 
the rest of the pattern from matching. 

Normally, SPANL must match at least one character. However, if the 
argument to SPANL contains no characters, then SPANL matches one or 
more line breaks. 


SIGNALED 



SPANL must appear in the right- 
hand side of an assignment 
statement. 

ERRORS 

TPU$_NEEDTOASSIGN 

ERROR 


TPU$_TOOFEW 

ERROR 

SPANL requires at least one 
argument. 


TPU$_TOOMANY 

ERROR 

SPANL accepts no more than one 
arguments. 


TPU$_ARGMISMATCH 

ERROR 

Argument passed to SPANL is of 
the wrong type. 


TPU$_CONTROLC 

ERROR 

You pressed CTRL/C during the 
execution of SPANL. 


EXAMPLES 

Q patl := SPANL (" ") 

This assignment statement stores a pattern in patl that matches the 
longest sequence of blank characters starting at the editing point and 
continuing until the search encounters a nonmatching character or the 
end of the buffer, range, or string. 


g pat2 := SPANL ("0123456789") 

This assignment statement stores in pat2 a pattern that matches the 
longest sequence of digits starting at the editing point and continuing 
until the search encounters a nonmatching character or the beginning or 
end of the buffer, range, or string. 

g pat3 := SPANL ("ABCDEFGHIJKLMNOPQRSTUVWXYZ") 

This assignment statement stores in pat3 a pattern that matches the 
longest sequence of the alphabetic characters listed in the parameter. If 
you use this pattern with the built-in procedure SEARCH, the search 
starts at the current character position and continues to an end-of- 
search condition. If you specify an EXACT search, the characters must 
be uppercase for a successful match. 
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0 PROCEDURE user_remove_numbers 
LOCAL patl, 

number_region; 

patl := SPANL ("0123456789"); 

POSITION (BEGINNING_OF (CURRENT_BUFFER)); 

LOOP 

number_region := SEARCH_QUIETLY (patl, FORWARD); 
EXITIF number_region = 0; 

ERASE (number_region); 

POSITION (number_region) ; 

ENDLOOP; 

POSITION (BEGINNING_OF (CURRENT__BUFFER) ) ; 
ENDPROCEDURE; 


This procedure removes all parts of a document that contain only numbers. 

@ PROCEDURE user_remove_blank_lines 
LOCAL patl, 

blank:_lines; 

patl := LINE__END + (SPANL ("") @ blank_lines) 

+ LINE__BEGIN; 

POSITION (BEGINNING_OF (CURRENT_BUFFER)); 

LOOP 

blank__lines := 0; 

SEARCH_QUIETLY (patl, FORWARD); 

EXITIF blank_lines = 0; 

ERASE (blank_lines); 

POSITION (blank_lines); 

ENDLOOP; 

POSITION (BEGINNING_OF (CURRENT_BUFFER)); 

ENDPROCEDURE; 


This procedure removes all empty lines from the current buffer. A line 
that contains only spaces or tabs is not empty. 

0 PROCEDURE user_find_mark_twain 

LOCAL patl, 

mark_twain; 

patl := "Mark" + (SPANL (" " + ASCII(9)) | SPANL ("")) 

+ "Twain"; 

mark_twain := SEARCH_QUIETLY (patl, FORWARD, NOEXACT); 

IF mark__twain = 0 
THEN 

MESSAGE ("String not found"); 

ELSE 

POSITION (mark_twain); 

ENDIF; 

ENDPROCEDURE; 


7-514 


This procedure positions you to the next occurrence of the text Mark 
Twain, where Mark and Twain may be separated by any number of spaces, 
tabs, or line breaks. 




VAXTPU Built-In Procedures 

SPAWN 


SPAWN 

Creates a subprocess running the command line interpreter. 

FORMAT 

SPAWN [(string, ])]l 

PARAMETERS 

String 

The command string that you want to be executed in the context of the 
subprocess that is created with SPAWN. 

ON 

A keyword indicating that control is to be returned to VAXTPU after the 
command has been executed. This is the default unless the value specified 
for the first parameter is the null string. 

OFF 

A keyword indicating that the user is to be prompted for additional 
operating system commands after the specified command has been 
executed. If the value specified for the first parameter is the null string, 
the default value for the second parameter is OFF. 

DESCRIPTION 

SPAWN suspends your VAXTPU process and spawns a VMS subprocess. 
This built-in procedure is especially usefiil for running programs and 
utilities that take control of the screen (these programs cannot be nm in a 
subprocess created with the built-in procedure CREATE_PROCESS). See 
Chapter 2 for a list of restrictions for subprocesses. 

If you are using DCL, you can return to your VAXTPU session after 
finishing in a subprocess by using either the DCL command ATTACH or 
the DCL command LOGOUT. If you use the DCL command ATTACH, 
the subprocess is available for future use. If you use the DCL command 
LOGOUT, the subprocess is deleted. When you return to the VAXTPU 
session, the screen is repainted. 

If you specify a DCL command as the parameter for SPAWN, the command 
is executed after the subprocess is created. When the command completes, 
the subprocess terminates, and control is returned to the VAXTPU process. 
If you want to remain in DCL, add the keyword OFF as the second 
parameter. 

SPAWN was designed to allow you to leave a VAXTPU session, do other 
work in a VMS subprocess, and return to the VAXTPU session that you 
interrupted. Subprocesses created with SPAWN give you direct access to 
the command line interpreter. These subprocesses are different from the 
subprocesses created with the built-in procedure CREATE_PROCESS. 
CREATE_PROCESS creates a subprocess within a VAXTPU session, and 
all of the output from the subprocess goes into a buffer. 
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SPAWN is not a valid built-in in DECwindows VAXTPU. However, if 
you are running non-DECwindows VAXTPU in a DECwindows terminal 
emulator, SPAWN works as described in this section. 

Note that SPAWN fails if you are running in an account with the 
CAPTIVE flag set in the authorization file. 

See the description of the built-in procedure ATTACH in this section for 
information on moving control from one subprocess to another. See the 
VMS DCL Dictionary for more information on the characteristics of a 
spawned subprocess. 

If the current buffer is mapped to a visible window, the SPAWN built-in 
causes the screen manager to synchronize the editing point, which is a 
buffer location, with the cursor position, which is a window location. This 
may result in the insertion of padding spaces or lines into the buffer if the 


cursor position is before the beginning of a line, in the middle of a tab, 
beyond the end of a line, or after the last line in the buffer. 

SIGNALED 

ERRORS 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the SPAWN built-in. 


TPU$JNVPARAM 

ERROR 

Wrong type of data sent to the 
SPAWN built-in. 


TPU$_REQUIRESTERM 

ERROR 

SPAWN is not a valid built-in in 
DECwindows VAXTPU. 


TPU$_UNKKEYWORD 

ERROR 

An unknown keyword has been 
used as an argument. Only ON or 
OFF is allowed. 


TPU$_BADKEY 

ERROR 

An unknown keyword has been 
used as an argument. Only ON or 
OFF Is allowed. 


TPU$_CAPTIVE 

WARNING 

Unable to create a subprocess In 
a captive account. 


TPU$_CREATEFAIL 

WARNING 

Unable to activate the subprocess. 


EXAMPLES 

Q SPAWN 

This spawns a VMS subprocess and suspends VAXTPU process. After 
completing work in the subprocess, you can return to your VAXTPU 
session by using the DCL command ATTACH or the DCL command 
LOGOUT. 

g SPAWN ("DIRECTORY") 

This spawns a VMS subprocess and executes the DCL command 
DIRECTORY. When the command completes, you are returned to your 
VAXTPU session. 
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s SPAWN ("SHOW LOGICAL SYS$LOGIN", OFF) 

This spawns a VMS subprocess and puts your VAXTPU process on hold. 
The DCL command is executed in the subprocess to show the translation 
of the logical name SYS$LOGIN, and you are left at the DCL prompt. 
After completing work in the subprocess, you can return to your VAXTPU 
session by using the DCL command ATTACH or the DCL command 
LOGOUT. 
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SPLIT_LINE 

Breaks the current line before the editing point and creates two lines. 

FORMAT 

SPLIT_LINE 

PARAMETERS 

None. 

DESCRIPTION 

SPLIT_LINE breaks the current line into two lines. The relative screen 
position of the line you are splitting may change as a result of this 
procedure. The first line contains any characters to the left of the editing 
point. The second line contains the rest of the characters. The new line 
that is created is inserted directly after the former current line. 

When you use SPLIT_LINE, the editing point remains on the same 
character, but that character is now the first character on the newly 
created line. 

If the editing point is not the first character in the line being split, the left 
margin of the old line is not changed. The new line, which contains the 
editing point and the characters to the right of the editing point, takes the 
buffer’s left margin as its own left margin. 

If the editing point is the first character of a line, SPLIT_LINE creates a 
blank line where the original line was. The left margin of this blank line 
is the buffer’s left margin. SPLIT^LINE moves the original line, including 
the editing point, to the line below the blank line. If the original line had 
a left margin different from the buffer’s current left margin, SPLIT_LINE 
preserves the original line’s left margin when it moves the line down. 

If the editing point is on a blank line, SPLIT_LINE creates a new blank 
line below the existing line. The editing point moves to the new blank line. 
The new blank line receives the buffer’s left margin value. If the original 
blank line had a left margin different from the buffer’s current left margin, 
the original blank line retains its margin. 

Using SPLIT_LINE may cause VAXTPU to insert padding spaces or blank 
lines in the buffer. SPLIT_LINE causes the screen manager to place the 
editing point at the cursor position if the current buffer is mapped to a 
visible window. (For more information on the distinction between the 
cursor position and the editing point, see Chapter 6.) If the cursor is not 
located on a character (that is, if the cursor is before the beginning of a 
line, beyond the end of a line, in the middle of a tab, or below the end of 
the buffer), VAXTPU inserts padding spaces or blank lines into the buffer 
to fill the space between the cursor position and the nearest text. 
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SIGNALED 

ERRORS 


TPU$_NOCURRENTBUF 

TPU$_NOCACHE 


WARNING You are not positioned in a buffer. 

ERROR There is not enough memory to 
allocate a new cache. 

WARNING You cannot modify an unmodifiable 
buffer. 

ERROR SPLIT_LINE takes no arguments. 


TPU$_NOTMODIFIABLE 


TPU$_TOOMANY 


EXAMPLES 

Q SPLIT__LINE 


This statement breaks the current line at the editing point and creates a 
new line. 


§ PROCEDURE user_split_line 

LOCAL old_position, 
new_position; 

SPLIT_LINE; 

IF (CURRENT_ROW = 1) AND (CURRENT_COLUMN = 1) 

THEN 

old_position := MARK (NONE); 

SCROLL (CURRENT_WINDOW, -1); 
new_position := MARK (NONE); 

!Make sure we scrolled before doing CURSOR_VERTICAL 
IF new_position <> old_position 
THEN 

CURSOR_VERTICAL (1)/ 

ENDIF; 

ENDIF; 

ENDPROCEDURE; 


This procedure splits a line at the editing point. If the editing point is row 
1, column 1, the procedure causes the screen to scroll. 
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STR 

Returns a string equivalent for an integer, a keyword, a string, or the contents 
of a range or buffer. 

FORMAT 

strings := STR 1 }, 

FORMAT 

Strings := STR 

[ stringl j 

PARAMETERS 

integerl 

The integer you want converted to a string. 

integer2 

The radix (base) you want VAXTPU to use when converting the first 
integer parameter to a string. The default radix is 10. The other allowable 
values are 8 and 16. 

keyword 

The keyword whose string representation you want. 

buffer 

The buffer whose contents you want returned as a string. 

range 

The range whose contents you want returned as a string. 

Stringl 

Any string. STR now accepts a parameter of t 3 T)e string, so you need not 
check the type of the parameter you supply to the built-in. 

strmg2 

A string specifying how you want line ends represented. The default is the 
null string. You can only use string2 if you specify a range or buffer as the 
first parameter. If you want to specify the keyword ON or OFF but do not 
want to specify string2, you must use a comma before the ke 3 rword as a 
placeholder, as follows: 

new_string ;= STR (old_buffer, , ON); 

ON 

A ke 5 rword directing VAXTPU to insert spaces preserving the white space 
created by the left margin of each record in the specified buffer or range. 
Specifically, if you specify a buffer or range with a left margin greater than 
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return value 


DESCRIPTION 


SIGNALED 

ERRORS 


1, the keyword ON directs VAXTPU to insert a corresponding number of 
spaces after the line ends in the resulting string. For example, if the left 
margin of the specified lines is 10 and you use the keyword ON, VAXTPU 
inserts 9 spaces after each line end in the resulting string. VAXTPU does 
not insert any spaces after line beginnings of lines that do not contain 
characters. If the first line of a buffer or range starts at the left margin, 
VAXTPU inserts spaces before the text in the first line. 

Note that you can only use this keyword if you specify a buffer or range as 
a parameter. 

OFF 

A keyword directing VAXTPU to ignore the left margin setting of the 
records in the specified buffer or range. This is the default. For example, 
if the left margin of the specified lines is 10 and you use the keyword OFF, 
VAXTPU does not insert any spaces after the line ends in the resulting 
string. 

Note that you can only use this keyword if you specify a buffer or range as 
a parameter. 


strings The string equivalent of the parameter you specify. 


If you use the first format shown above, STR returns a string 
representation of an integer or a ke 3 rword. You can then use the variable 
containing the returned string in operations that require string data types. 
For another method of generating a string representation of an integer, 
see the description of the built-in procedure FAO. 

If you use the second format shown above, STR returns a string equivalent 
for any string or for the contents of a range or buffer. 


TPU$_TRUNCATE 

WARNING 

You specified a buffer or range 
so large that converting it would 
exceed the maximum length for 
a string. VAXTPU has truncated 
characters from the returned 
string. 

TPU$_NEEDTOASSIGN 

ERROR 

STR must appear on the right- 
hand side of an assignment 
statement. 

TPU$_TOOFEW 

ERROR 

STR requires at least one 
argument. 

TPU$_TOOMANY 

ERROR 

STR accepts only two arguments. 

TPU$JNVPARAM 

ERROR 

The argument to STR must be an 
integer, buffer, string, or range. 

TPU$_BADVALUE 

ERROR 

You specified a value other than 8, 


10, or 16 for the radix parameter. 
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EXAMPLES 

D return_string := STR (SELECT_RANGE, "<CRLF>", ON); 

This statement creates a string using the text in the select range. Line 
breaks are marked with the string CRLF, The white space created by the 
margin is preserved by inserting spaces after the line breaks. 

g still_a_string ;= STR ("confetti"); 

This statement assigns the string confetti to the variable stilljajstring. 

g new_numbers := STR (123) 

This assignment statement stores the string "123" in the variable new_ 
numbers, 

Q the_string := STR (32, 16) 

This assignment statement assigns the string "00000020" to the variable 
thejstring, 

g the___string := STR (32, 10) 

This assignment statement assigns the string "32" to the variable the_ 
string. 

g PROCEDURE user_display_position 

vl := GET__INFO (second_window, "current_column"); 

MESSAGE ("Column: " + STR (vl)); 

v2 := GET_INFO (second__window, "current_row") ; 

MESSAGE ("Row: " + STR (v2)); ” 

ENDPROCEDURE; 


This procedure uses the built-in procedure STR to convert the integer 
variables vl and v2 to strings so that your row and column position can be 
displayed in the message area. 

g this_string := STR (this_range, "EOL") 


This statement forms a string using the text in the range "this_range." In 
the string, each end-of-line is represented by the letters EOL. For example, 
suppose the text in "this_range" is as follows: 

Sufficient unto the day 
are the cares thereof 

Given this text in "this_range", "this_string" contains the following: 

Sufficient unto the dayEOLare the cares thereof 

If "this^range" extends to the character after the "f' in "thereof, "this_ 
string" contains the following: 

Sufficient unto the dayEOLare the cares thereofEOL 
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SUBSTR 


Returns a string that represents a substring of a buffer, range, or string. 


FORMAT r buffer 1 

string2 := SUBSTR (< range >, integerl [, integer2J) 

[ string J 


PARAMETERS buffer 

The buffer that contains the substring. 

range 

The range that contains the substring. 

String 

The string that contains the substring. 

integerl 

The character position at which the substring starts. The first character 
position is 1. 

integer2 

The number of characters to include in the substring. If you do not specify 
t.big parameter, VAXTPU sets the returned string’s end point to the end of 
the first parameter. 


r6turn valUG A string representing a substring of a string or range. 


QggQpiP'piQ^ If you specify a larger number of characters for integer2 than are present 

in the substring, only the characters present are returned in string2. No 


error is signaled. 

SIGNALED 

ERRORS 

TPU$_NEEDTOASSIGN 

ERROR 

SUBSTR must appear on the 
right-hand side of an assignment 
statement. 


TPU$_TOOFEW 

ERROR 

SUBSTR requires three 
arguments. 


TPU$_TOOMANY 

ERROR 

SUBSTR accepts only three 
arguments. 


TPU$JNVPARAM 

ERROR 

One of the arguments to SUBSTR 
is of the wrong type. 


TPU$_ARGMISMATCH 

ERROR 

One of the arguments to SUBSTR 
is of the wrong type. 
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TPU$_TRUNCATE WARNING You specified a buffer or range so 

large that returning the requested 
substring would exceed the 
maximum length for a string. 
VAXTPU has truncated characters 
from the returned string. 


EXAMPLES 

D file_type := SUBSTR ( "login.com", 7, 3) 

This assignment statement returns the string "com” in the variable file_ 
type. The substring starts at the seventh character position (“c”) and 
contains three characters (“com”). If you use a larger number for integer2, 
for example, 7, the variable filejtype still contains "com" and no error is 
signaled. 

§ ! Capitalize the first letter in a string. 

I 

PROCEDURE user_initial_cap (my_string) 

LOCAL 

f irst_part__of_string, 
rest__of_string, 
first_letter, 
cur__loc; 

cur_loc := 1; 

first_part_of_string := ""; 
rest_of_string := ""; 

LOOP 

first_letter := SUBSTR (my_string, cur_loc, 1); 

EXITIF first_letter = ""; 

EXITIF (first_letter >= "a") AND (first_letter <= "z"); 

EXITIF (first_letter >= "A") AND (first^letter <= "Z"); 
cur_loc := cur_loc + 1; 

ENDLOOP; 

CHANGE_CASE (first_letter, UPPER); 

first_part_of_string := SUBSTR (my__string, 1, cur_loc - 1); 
rest_of_string ;= SUBSTR (my_string, cur_loc -i- 1 , 

LENGTH (my_string) - cur_loc); 

my_string := first_part_of_string + first_letter 
+ rest_of_string; 

ENDPROCEDURE; 


This procedure capitalizes the first character in a string. It does not affect 
any other characters in the string. It makes use of the fact that SUBSTR 
returns a null string if the second parameter points past the end of the 
string. 
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first_ten_characters := SUBSTR (CURRENT_BUFFER, 1, 10); 
buffer_range := CREATE_RANGE (BUFFER_BEGIN, BUFFER_END, NONE); 
same_ten_characters := SUBSTR (rl, 1, 10); 

I 

! Leaving the last parameter off means "go to the end". 

I 

a_string := "abcdefghijk"; 

IF SUBSTR (a^string, 5, length (a_string)) <> SUBSTR (a_string, 5) 
THEN 

MESSAGE ('This message will never be displayed.'); 

ELSE 

MESSAGE ('This message is always displayed.'); 

ENDIF; 

These two calls to SUBSTR return the same value. 
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TRANSLATE 


Substitutes one set of specified characters for another set. TRANSLATE 
returns a value for the translated range or buffer or for the string 
representation of the translated text. TRANSLATE is based on the Run¬ 
Time Library (RTL) routine STR$TRANSLATE. For complete information on 
STR$TRANSLATE, see the VMS RTL String Manipulation (STR$) Manual. 


FORMAT 


bufferl 

rangel 

stringl 


I := TRANSLATE 


( buffer2 'I 

( < range2 >, strings, string4 
[ string2 J 


[T / IN_PLACE 
[[ ' \ NOTJN_PLACE 



PARAMETERS buffer2 

A buffer in which one or more characters are to be replaced. Note that you 
cannot use the keyword NOT_IN_PLACE if you specify a buffer for the 
first parameter. 

range2 

A range in which one or more characters are to be replaced. Note that you 
caimot use the ke 3 rword NOT_IN_PLACE if you specify a r 2 inge for the 
first parameter. 

string2 

A string in which one or more characters are to be replaced. If a return 
value is specified, the substitution is performed in the returned string. If 
you specify IN_PLACE for the third parameter, TRANSLATE makes the 
specified change to the string specified in the first parameter. Note that if 
Strings is a constant, IN_PLACE has no effect. 

Strings 

The string of replacement characters. 

string4 

The literal characters within the text specified by parameterl that are to 
be replaced. 

IN_PLACE 

A kejrword directing VAXTPU to make the indicated change in the buffer, 
range, or string specified. This is the default. 

NOTJN_PLACE 

A keyword directing VAXTPU to leave the specified string unchanged 
and return a string that is the result of the specified translation. You 
cannot use NOT_IN_PLACE if the first parameter is specified as a range 
or buffer. To use NOT_IN_PLACE, you must specify a return value for 
TRANSLATE. 
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return values 


DESCRIPTION 


SIGNALED 

ERRORS 


bufferl 

A variable of type buffer pointing to the buffer containing the modified 
text, if you specify a buffer for the first parameter. The variable "retumed_ 
buffer" points to the same buffer pointed to by the buffer variable specified 
as the first parameter. 

rangel 

A range containing the modified text, if you specify a range for first 
parameter. The returned range spans the same text as the range specified 
as a parameter, but they are two separate ranges. If you subsequently 
change or delete one of the ranges, this has no effect on the other range. 

stringl 

A string containing the modified text, when you specify a string for the 
first parameter. TRANSLATE can return a string even if you specify IN_ 
PLACE. 


The TRANSLATE built-in searches the text specified by the first 
parameter for the characters contained in the third parameter. When 
VAXTPU finds the sequence specified by stringS, VAXTPU substitutes the 
first character in string2 for the first character in stringS, and so forth. 

If the translate string, string2, is shorter than the match string, strings, 
and the number of matched character positions is greater than the number 
of character positions in the translate string, the treinslation character is a 
space. 

The IN_PLACE and NOT_IN_PLACE keywords specify whether the 
source is to be changed. IN_PLACE means that the source is modified, 
while NOT_IN_PLACE indicates that the source is not changed. 


TPU$_TOOFEW 

ERROR 

TRANSLATE requires three 
arguments. 

TPU$_TOOMANY 

ERROR 

TRANSLATE accepts no more 
than three arguments. 

TPU$_ARGMISMATCH 

ERROR 

One of your arguments to 
TRANSLATE is of the wrong 
data type. 

TPU$JNVPARAM 

ERROR 

One of your arguments to 
TRANSLATE is of the wrong 
data type. 

TPU$_NOTMODIFIABLE 

WARNING 

You cannot translate text in an 
unmodifiable buffer. 

TPU$_CONTROLC 

ERROR 

You pressed CTRL/C during the 
execution of TRANSLATE. 
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EXAMPLES 

D TRANSLATE (second_buffer, 

This statement replaces any lowercase “i” in secondjbuffer with an 
uppercase “I”. 

§ ! Procedure to translate characters to decipher scrambled text. 

! Characters are shifted 13 places for encryption. 

PROCEDURE user_trans_text ( text_to_translate ) 

TRANSLATE (text_to_translate, 

"NOPQRSTUVWXYZABCDEFGHIJKLMnopqrstuvwxyzabcdefghijklm", 
"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"); 

ENDPROCEDURE; 

This procedure translates the text you specify as "text_to_translate” 
according to the following pattern: any “A” is converted to an “N”; any “B” 
is converted to an “O”; and so on. 

g PROCEDURE user_strip_eighth 

LOCAL i, ! Loop counter 

seven, ! ASCII (0) through ASCII (127) 

eight; ! ASCII (128) through ASCII (255) 

! Build translate strings 

seven := 
eight := 
i := 0; 

LOOP 

seven := seven + ASCII (i); 
eight := eight + ASCII (i + 128); 
i := i + 1; 

EXITIF i = 128; 

ENDLOOP; 

TRANSLATE (CURRENT_BUFFER, seven, eight); 

ENDPROCEDURE; 


This procedure strips the eighth bit from all characters in the current 
buffer. A procedure like this is useful for reading files from systems 
like TOPS-20 on which the eighth bit is set without using the DEC 
Multinational Character Set. 

The following statements show how the asterisk (*) character can replace 
the character r during an interactive session. Suppose the following text is 
written in a buffer and that the variable "the_range" spans this text: 

This darned wind is a darned nuisance, darn it! 

The following statement assigns to "the_string" the characters in "the_ 
range": 

the_string := STR (the_range) 
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The following statement assigns to translated_string the text that results 
when an asterisk is substituted for each "r": 

translated_string := TRANSLATE (the_string, "r", NOT_IN_PLACE) 

The variable "translated_string" then contains the following text: 

This da*ned wind is a da*ned nuisance, da*n it! 

Note that if the text contained other r’s, they would also be replaced by 
asterisks. 
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UNANCHOR 



Specifies that the next pattern element may match anywhere after the 
previous pattern element. 

FORMAT 

UNANCHOR 

PARAMETERS 

None. 

DESCRIPTION 

Normally, when a pattern contains several concatenated or linked pattern 
elements, the pattern matches only when the text that matches one 
particular pattern element immediately follows the text that matches the 
previous pattern element. If UNANCHOR appears between two pattern 
elements, the text that matches the second pattern element may appear 
anywhere after the text that matches the first pattern element. 

Although UNANCHOR behaves much like a built-in, it is actually a 
ke5rword. 

For more information on patterns or pattern searching, see Chapter 2. 

SIGNALED 

ERRORS 

UNANCHOR is a ke 3 rword and has no completion codes. 


EXAMPLES 

D patl := "a" + UNANCHOR + ”123" 

This assignment statement creates a pattern that matches any text 
beginning with the letter a and ending with the digits 123, Any amount of 
text may appear between the a and the 123, 

g patl ;= UNANCHOR + "al23"; 


This assignment statement creates a pattern that matches from the search 
start position (the current position if searching the current buffer) through 
to and including the first occurrence of the string al23. 
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PROCEDURE user_remove_paren_text (paren_buffer) 

LOCAL patl, 

paren_text, 
searched_text; 

patl := "(" + UNANCHOR + 
searched__text ;= paren_buffer; 

LOOP 

paren_text := SEARCH_QUIETLY (patl, FORWARD, EXACT, 

searched_text); 

EXITIF paren_text = 0; 

ERASE (paren_text); 

searched_text := CREATE_RANGE (END_OF (paren_text), 

END__OF (paren_buffer) , NONE) ; 

ENDLOOP; 

ENDPROCEDURE; 

This procedure removes all parenthesized text from a buffer. The text may 
span several lines. It does not handle multiple levels of parentheses. 
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UNDEFINE_KEY 

Removes the current binding from the key that you specify. 


FORMAT 


UNDEFINE KEY (keyword If , ( l<ey-map-list-name | Tl^ 
- ' [[ \ key-map-name J Jj' 


PARAMETERS keyword 

The name of a key or key combination that VAXTPU allows you to define. 
See Table 2-1 for a list of the valid VAXTPU key names. 

key-map-UsUname 

Specifies a key map list in which the key is defined. The first definition 
of the key in the key maps that make up the key map list is deleted. If 
neither a key map nor a key map list is specified, the key map list bound 
to the current buffer is used. 

key-map-name 

Specifies a key map in which the key is defined. The first definition of the 
key in the key map is deleted. If neither a key map nor a key map list is 
specified, the key map list bound to the current buffer is used. 


DESCRIPTION After you use UNDEFINE_KEY, the key you specify is no longer defined. 

VAXTPU does not save any previous definitions that you may have 
associated with the key. However, any definitions of the specified key 
in key maps or key map lists other than the ones you specified are not 
removed. 

VAXTPU writes a message to the message buffer telling you that the key 
is undefined if you try to use it after you have undefined it. 


SIGNALED 

ERRORS 

TPU$_NODEFINITION 

WARNING 

There is no definition for this key. 

TPU$_NOTDEFINABLE 

WARNING 

First argument is not a valid 
reference to a key. 


TPU$_NOKEYMAP 

WARNING 

Second argument is not a defined 
key map. 


TPU$_NOKEYMAPLIST 

WARNING 

Second argument is not a defined 
key map list. 


TPU$_KEYMAPNTFND 

WARNING 

The key map listed in the second 
argument is not found. 


TPU$_EMPTYKMLIST 

WARNING 

The key map list specified in the 
second argument contains no key 
maps. 
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TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
UNDEFINE_KEY built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the UNDEFINE_KEY built-in. 

TPU$JNVPARAM 

ERROR 

Wrong type of data sent to the 
UNDEFINE KEY built-in. 


EXAMPLES 

UNDEFINE__KEY (CTRL_Z_KEY) 

This statement removes the association between the key combination 
CTRL/Z and the code that it previously executed. 

! Parameters: 

I 

! Name Function Input or Output? 


! which_key Keyword for key to clear input 

PROCEDURE user_clear_key (which_key) 

IF (LOOKUP_KEY (which_key, PROGRAM) <> 0) 

THEN 

UNDEFINE_KEY (which_key); 

ELSE 

MESSAGE ("Key not defined"); 

ENDIF; 

ENDPROCEDURE; 

This procedure undefines a key. A procedure like this can be used by 
keypad initialization procedures. 

PROCEDURE delete_all_definitions 
LOCAL key; 

LOOP 

key := GET_INFO (DEFINED__KEY, "first", "tpu$key_map"); 

EXITIF key = 0; 

UNDEFINE_KEY (key, "tpu$key_map"); 

ENDLOOP; 

ENDPROCEDURE; 


This procedure deletes all of the key definitions in the key map TPU$KEY_ 
MAP. 
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UNMANAGE_WIDGET 

Makes the specified widget and all of its children invisible. 

For more information about managing widgets, see the VMS DECwindows 



Toolkit Routines Reference Manual. 

FORMAT 

UNMANAGE_WIDGET (widget [, widget... ]) 

PARAMETERS 

widget 

The widget instance to be unmanaged. 

DESCRIPTION 

If you want to unmanage several widgets that are children of the seune 
parent, but you do not want to unmanage the parent, include all the 
children in a single call to UNMANAGE_WIDGET. Unmanaging several 
widgets at once is more efficient than unmanaging one widget at a time. 

The UNMANAGE_WIDGET built-in is equivalent to the X Toolkit 
UNMANAGE CHILD and UNMANAGE CHILDREN routines. 


SIGNALED 

ERRORS 


TPU$JNVPARAM 

ERROR 

TPU$_TOOFEW 

ERROR 

TPU$_NORETURNVALUE 

ERROR 

TPU$_REQUIRESDECW 

ERROR 

TPU$_WIDMISMATCH 

ERROR 


You specified a parameter of the 
wrong type. 

Too few arguments passed to the 
UNMANAGE^WIDGET built-in. 

UNMANAGE_WIDGET cannot 
return a value. 

You can use the UNMANAGE_ 
WIDGET built-in only if you are 
using DECwindows VAXTPU. 

You have specified a widget whose 
class is not supported. 


EXAMPLE 

PROCEDURE eve$$replace__clean_up 

ON__ERROR 

[TPU$_CONTROLC]: 

eve $1ea rn_abo rt; 
abort; 

[OTHERWISE]: 

eve$$replace_error_handler; 

ENDON_ERROR; 

IF NOT eve$$x_replace_array {eve$$k_replace_asking} 

THEN ! If all occurrences were replaced, the editing 

! point is positioned to the last saved mark. 
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POSITION (eve$$x_replace_array {eve$$k_replace_saved_mark}); 

ENDIF; 

! Restore the buffer's original direction and mode. 

SET (eve$$x__replace_array {eve$$k_replace__saved_direction}, 
eve$$x_replace_array {eve$$k_replace_this_buffer}); 

SET (eve$$x_replace_array {eve$$k_replace_saved_mode}, 

eve$$x_replace__array {eve$$k__replace_this_buf fer}) ; 

SET (SCREEN_UPDATE, ON); 
eve$message (EVE$_REPLCOUNT, 0, 

eve$$x_replace_array {eve$$k__replace_occurrences}) ; 

IF (eve$$x_state__array {eve$$k__command_line_flag} = eve$k_invoked__by_menu) 

AND (eve$$x_state__array {eve$$k_dialog_box}) 

THEN 

IF eve$x_decwindows_active 
THEN 

IF GET_INFO (eve$x_replace_each_dialog, "type") = WIDGET 
THEN 

UNMANAGE_WIDGET (eve$x_replace_each_dialog); ! This statement 

! unmanages the 
! replace dialog 
! box. 

ENDIF; 

ENDIF; 

ENDIF; 

ENDPROCEDURE; 

This procedure shows one possible way that a layered application can use 
the UNMANAGE_WIDGET built-in. The procedure is a modified version 
of the EVE procedure EVE$$REPLACE_CLEAN_UP. You can find the 
original version in SYS$EXAMPLES:EVE$EDIT.TPU. 

The procedure performs screen cleanup operations after the user has used 
the EVE command REPLACE. It restores the direction and mode to which 
the buffer was set before the replace operation began, then tests whether 
the replace dialog box is present and, if so, makes it invisible. 


7-535 








VAXTPU Built-In Procedures 

UNMAP 


UNMAP 

Disassociates a window from its buffer and removes the window or widget 
from the screen. 

FORMAT 

<{ sr }> 

PARAMETERS 

window 

The window you want to remove from the screen. 

widget 

The widget instance you want to make invisible. 

DESCRIPTION 

If you unmap the current window, VAXTPU tries to move the cursor 
position to the window that was most recently the current window. The 
window in which VAXTPU positions the cursor becomes the current 
window, and the buffer that is associated with this window becomes the 
current buffer. 

The screen area of the window you unmap is either erased or returned to 
any windows that were occluded by the window you unmapped. VAXTPU 
returns lines to adjacent windows if the size of the windows requires the 
lines that were used for the window you unmap. The size of a window is 
determined by the values you specified for the built-in procedure CREATE^ 
WINDOW when you created the window, or by the values you specified for 
the built-in procedure ADJUST_WINDOW if you changed the size of the 
window. If adjacent windows do not require the lines that were used by 
the window you unmap, the lines that the window occupied on the screen 
remain blank. 

The window that you unmap is not deleted from the hst of available 
windows. You can cause the window to appear on the screen again with 
MAP. UNMAP does not have any effect on the buffer that was associated 
with the window being unmapped. 

Note that unmapping a widget does not delete the widget. Future MAP 
operations will make the widget visible again. 

SIGNALED 

ERRORS 

TPU$_TOOFEW ERROR UNMAP requires one parameter. 

TPU$_TOOMANY ERROR UNMAP accepts only one 

parameter. 

TPU$JNVPARAM ERROR One or more of the specified 

parameters have the wrong type. 
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TPU$_WINDNOTMAPPED WARNING Window is not mapped to a buffer. 


EXAMPLES 

Q UNMAP (main_window) 

This statement removes the main window from the screen and 
disassociates from the main window the buffer that was mapped to it. 

§ PROCEDURE user___one_window_to_two 

LOCAL wind_length, 
wind__half, 
first_line, 
last_line; 

cur_wind := CURRENT_WINDOW; 

! If it exists 

IF (cur_wind <> 0) 

THEN 

first_line := GET_INFO (cur__wind, "visible_top"); 
last_line := GET_INFO (cur_wind, "visible_bottom"); 
wind_buf := GET_INFO (cur__wind, "buffer"); 

UNMAP (cur_wind); 

ELSE 

! If there is no current window then create an empty buffer 
first_line := 1; 

last_line :=GET_INFO (SCREEN, "visible_length"); 
wind_buf := CREATE_BUFFER ("Empty Buffer"); 

ENDIF; 

wind_length := (last_line “ first_line) + 1; 
wind_half := wind__length/2; 

new_window___l := CREATE_WINDOW (first__line, wind_half, OFF) ; 

SET (VIDEO, new__window_l, UNDERLINE); 
new_window_2 := CREATE_WINDOW (wind_half+l, 
last_line-wind_half, OFF); 

! Associate the same buffer with both windows 
! and map the windows to the screen 

MAP (new_window_l, wind_buf); 

MAP (new_window_2, wind_buf); 

ENDPROCEDURE; 

This procedure unmaps the current window and puts two new windows in 
its place. (Note that if the window that you are replacing has a status hne, 
this line is not included in the screen area used by the two new windows. 
This is because GETJNFO (window, ’'visible_bottom") does not take the 
status line into account.) 

§ UNMAP (example_widget); 

This statement causes the widget assigned to the variable examplejjuidget 
to become invisible. 
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UPDATE 

Causes the screen manager to make a window reflect the current internal 
state of the buffer that is associated with the window. One important task that 
UPDATE performs is to move the cursor to the editing point if the cursor and 
the editing point are not synchronized when the UPDATE built-in is executed. 

FORMAT 

UPDATE 1; 

1 window ) 

PARAMETERS 

ALL 

A keyword directing VAXTPU to make all visible windows reflect the 
current state of the buffers mapped to them. 

window 

The window that you want updated. The window must be mapped to the 
screen for the update to occur. 

DESCRIPTION 

The screen manager updates windows after each keystroke. However, if a 
key has a procedure bound to it, VAXTPU may execute many statements 
when that key is pressed. By default, UPDATE does not reflect the result 
of any statement in a procedure bound to a key until all the statements in 
the procedure have been executed. As a result, the screen may not reflect 
the current state of the buffer during execution of a procedure bound to a 
key. If you want the screen to reflect changes before the entire procedure 
is executed, you can force an immediate update by adding an UPDATE 
statement to the procedure. 

UPDATE (window) affects a single window that is visible on the screen. If 
the buffer associated with the window you use as a parameter is associated 
with other windows that are mapped to the screen, all of these windows 
may be updated. 

UPDATE (ALL) updates all visible windows. The difference between the 
UPDATE (ALL) built-in and the REFRESH built-in is that UPDATE 
(ALL) makes whatever changes are necessary on a window-by-window 
basis. REFRESH clears the screen and repaints everything from scratch, 
as well as reinitializing scrolling regions and other terminal-dependent 
settings. 

For more information on the results of the REFRESH built-in, see the 
description of REFRESH in this chapter. For more information on how 
the VAXTPU screen manager uses the UPDATE built-in in various 
circumstances, see Chapter 6. 
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SIGNALED 




ERRORS 

TPU$_TOOFEW 

ERROR 

UPDATE requires one parameter. 

TPU$_TOOMANY 

ERROR 

You specified more than one 
parameter. 


TPU$JNVPCARAM 

ERROR 

The specified parameter has the 
wrong type. 


TPU$_BADKEY 

ERROR 

The keyword must be ALL. 


TPU$_UNKKEYWORD 

ERROR 

You specified an unknown 
keyword. 


TPU$_WINDNOTMAPPED 

WARNING 

You cannot update a window that 
is not on the screen. 


EXAMPLES 

Q UPDATE (new_window) 

This statement causes the screen manager to make newjuuindow reflect 
the current internal state of the buffer associated with newjuuindow. 

§ PROCEDURE user_show_first_line 

LOCAL old_position^ ! Marker of position before scroll 

new_position; ! Marker of position after scroll 

UPDATE (CURRENT_WINDOW); 

IF (GET_INFO (CURRENT_WINDOW, "current_row") = 

GET_INFO (CURRENT_WINDOW, "visible_top")) 

AND 

(CURRENT_COLUMN = 1) 

THEN 

old_position := MARK (NONE); 

SCROLL (CURRENT_WINDOW, -1); 
new_position := MARK (NONE); 

! Make sure we scrolled before doing the CURSOR_VERTICAL 

IF new_position <> old_position 
THEN 

CURSOR__VERTICAL (1) / 

ENDIF; 

ENDIF; 

ENDPROCEDURE; 


This procedure updates the screen to display the new line of text that you 
are inserting before the top line of the window. (When you insert text in 
front of the top of a window, the included text is not visible on the screen 
unless you use a procedure such as this one to ensure that the text is 
displayed.) 
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WRITE CLIPBOARD 



Writes string format data to the clipboard. 

FORMAT 

r buffer ] 

WRITE_CUPBOARD ( clipboardjabel, 1 range W 

[ string ) 

PARAMETERS 

clipboardjabel 

The label for multiple entries in the clipboard. Since the clipboard does 
not currently support multiple labels, use any string, including the null 
string, to specify this par 2 uneter. 

buffer 

The buffer containing text to be written to the clipboard. VAXTPU 
represents line breaks by a hne-feed character (ASCII (10)). If you specify 
a buffer, VAXTPU converts the buffer to a string, replacing line breaks 
with line feeds, and replacing the white space before the left margin with 
padding blanks. 

The buffer must contain at least one character or line break. If it does not, 
VAXTPU signals TPU$_CLIPBOARDZERO. 

range 

The range containing text to be written to the clipboard. VAXTPU 
represents line breaks by a hne-feed character (ASCII (10)). If you specify 
a range, VAXTPU converts the range to a string, replacing line breaks 
with line feeds, and replacing the white space before the left margin with 
padding blanks. 

The range must contain at least one character or line break. If it does not, 
VAXTPU signals TPU$_CLIPBOARDZERO. 

String 

The string containing text to be written to the clipboard. The string must 
contain at least one character. If it does not, VAXTPU signals TPU$ 
CLIPBOARDZERO. 

DESCRIPTION 

The clipboardjabel parameter provides support for multiple entries on 
the clipboard; at present, however, the clipboard does not support multiple 
entries. 
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SIGNALED 

ERRORS 


TPU$_CLIPBOARDLOCKED 

WARNING 

The clipboard is locked by another 
process. 

TPU$_CLIPBOARDZERO 

WARNING 

The data to be written to the 
clipboard have zero length. 

TPU$_TRUNCATE 

WARNING 

VAXTPU has truncated characters 
from the data written because 
you specified a buffer or range 
containing more than 65,535 
characters. 

TPUSJNVPARAM 

ERROR 

One of the parameters was 
specified with data of the wrong 
type. 

TPU$_NORETURNVALUE 

ERROR 

WRITE_CLIPBOARD cannot 
return a value. 

TPU$_REQUIRESDECW 

ERROR 

You can use the WRITE_ 
CLIPBOARD built-in only if you 
are using DECwindows VAXTPU. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to the 
WRITE^CLIPBOARD built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the WRITE_CLIPBOARD built-in. 


EXAMPLES 

D WRITE_CLIPBOARD this_range); 

This statement writes the contents of the range this_range to the 
clipboard. 

§ PROCEDURE eve$$cut_copy (delete_range) 

LOCAL remove_range, ! Local copy of the currently 

! selected range. 

done_message; ! Success message. 

ON_ERROR 

[TPU$_CLIPBOARDLOCKED]: 

eve$message (EVE$_CLIPBDWRITLOCK); 
eve$learn_abort; 

RETURN (FALSE); 

[OTHERWISE]: 

eve $1ea rn_abo rt; 

ENDON__ERROR; 

remove_range := eve$selection (TRUE); 

IF remove_range <> 0 
THEN 

WRITE_CLIPBOARD (""/ remove_range); ! This statement writes a copy 

! of the selected range to the 
! clipboard. 
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IF delete_range 
THEN 

done_message ;= EVE$__REMCOMPL/ 
ERASE (remove_range); 

ELSE 

done_message := EVE$_COPYCOMPL; 
ENDIF; 

remove_range := 0; 

eve$message (done__message) ; 

RETURN (TRUE); 

ENDIF; 

eve$learn_abort; 

RETURN (FALSE); 

ENDPROCEDURE; 


This procedure shows one possible way that a layered application csin 
use the WRITE_CLIPBOARD built-in. This procedure is a copy of 
the EVE procedure EVE$$CUT_COPY. You can find this procedure in 
SYS$EXAMPLES:EVE$DECWINDOWS.TPU. 

The procedure checks whether a selection is active and, if so, writes the 
contents of the selected range to the clipboard. If the user has directed 
EVE to cut the selected text, the procedure erases the selected range. 
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WRITE FILE 



Writes data to the file that you specify. WRITE_FILE optionally returns a string 
that is the file specification of the file created. 

FORMAT 

|strlng2 := ] WRITE.FILE ( | | [.stringl |j 

PARAMETERS 

buffer 

The buffer whose contents you want to write to a file. 

range 

The range whose contents you want to write to a file. 

If you use WRITE_FILE on a range that does not start at the left margin 
of a line, VAXTPU does the following: 

• Determines the left margin of the line in which the range starts 

• Writes the range to the output file starting at the same left margin as 
the margin of the line where the range starts 

For example, if you write a range that starts in column 30 of a line whose 
left margin is 10, WRITE_FILE writes the range in the output file starting 
at column 10. 

string 1 

A string specifying the file to which the contents of the buffer are to be 
written. If you do not specify a full file specification, VAXTPU determines 
the output file specification using the current device and directory as 
defaults. 

This parameter is optional. If you omit it, VAXTPU uses the associated 
output file name for the buffer. If there is no associated file name, 
VAXTPU prompts you for one. If you do not give a file name at the 
prompt, VAXTPU does not write to a file. In that case, the optional string2 
that is returned is a null string. 

return value 

A string representing the file specification of the file created. 

DESCRIPTION 

If you specify a result, WRITE__FILE returns a string that is the file 
specification of the file to which the data was written. 

VAXTPU uses a flag to mark a buffer as modified or not modified. When 
you write data from a buffer to an external file, VAXTPU clears the 
modified flag for that buffer. If you do not make any further modifications 
to that buffer, VAXTPU does not consider the buffer as being modified and 
does not write out the file by default when you exit. If an error occurs 
while VAXTPU is writing a file, VAXTPU does not clear the modified flag. 
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When the contents of a buffer are written to a file, the associated journal 
file (if any) is closed and deleted and a new journal file is created. The 
new file contains the name of the file to which the buffer was written. 

Note that deleting the file that has been written out invalidates the buffer 
change journal. 

See Appendix F for a list of the file types that VAXTPU supports. 


SIGNALED 

ERRORS 


TPU$_CONTROLC 

ERROR 

The execution of the write 
operation terminated because 
you pressed CTRLyC. 

TPU$_TOOFEW 

ERROR 

WRITE__FILE requires at least one 
parameter. 

TPU$_TOOMANY 

ERROR 

WRITE_FILE accepts no more 
than two parameters. 

TPU$_ARGMISMATCH 

ERROR 

One of the parameters to WRITE_ 
FILE is of the wrong type. 

TPUSJNVPARAM 

ERROR 

One of the parameters to WRITE_ 
FILE Is of the wrong type. 

The following completion codes can be signaled by VAXTPtPs file 

I/O routine. You can provide your own file I/O routine by using the 
VAXTPU callable interface. If you do so, WRITE_FILE’s completion 
status depends upon what status you signaled in your file I/O routine. 

TPU$_OPENOUT 

ERROR 

WRITE_FILE could not create the 
output file. 

TPU$_NOFILEACCESS 

ERROR 

WRITE_FILE could not connect to 
the newly created output file. 

TPU$_WRITEERR 

ERROR 

WRITE_FILE could not write 
the text to the file because it 
encountered a file system error 
during the operation. 

TPU$_CLOSEOUT 

ERROR 

WRITE_FILE encountered a file 
system error closing the file. 


EXAMPLES 

Q WRITE_FILE (paste_buffer, "myfile.txt") 

This statement writes the contents of the paste buffer to the file named 
MYFILE.TXT. 

§ my_file := WRITE_FILE (select_range, "myfile.txt") 

This assignment statement puts the file name to which the select_range is 
written in the string my_file. 
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PROCEDURE user_write_file 

WRITE_FILE (extra_buf); 

DELETE (extra_window); 

DELETE (extra_buf); 

! Return the lines from extra__window to the main window 
ADJUST_WINDOW (main_window, -11, 0); 


ENDPROCEDURE; 



This procedure writes the contents of a buffer called extra J)uf to a file 
(because you do not specify a file name, the associated file for the buffer is 
used). The procedure then removes the extra window and buffer from your 
editing context. 
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WRITE, 

_GLOBAL_SELECT 




Sends requested information about a giobai selection from the VAXTPU 
layered application to the application that issued the information request. 

FORMAT 


' array 




buffer 



WRITE_GLOBAL_SELECT (< 

range 
string 
integer 
. NONE , 

0 




PARAMETERS array 

An array that passes information about a global selection whose contents 
describe information that is not of a data type supported by VAXTPU. For 
example, the array could pass information about a pixmap, an icon, or a 
span. 

VAXTPU does not use or alter the information in the array; the application 
layered on VAXTPU is responsible for determining how the information 
is used, if at all. Since the array is used to pass information to and from 
other DECwindows apphcations, all applications that send or receive 
information whose data type is not supported by VAXTPU must agree on 
how the information is to be sent and used. 

The application sending the information is responsible for creating the 
array and giving it the proper structure. The array’s structure is as 
follows: 

• The element array {0} contains a string naming the data type of 
the information being passed. For example, if the information being 
passed is a span, the element contains the string "SPAN". 

• The element array (1} contains either the integer 8, indicating that the 
information is passed as a series of b 3 d;es, or the integer 32, indicating 
that the information is passed as a series of longwords. 

• If array (1} contains the value 8, the element array {2} conteuns a 
string and there are no array elements after array (2). The string 
does not name an 5 fthing, but rather is a series of bytes. As mentioned, 
the meaning and use of the information is agreed upon by convention 
among the DECwindows applications. 

• If array {1} contains the value 32, the remaining elements of the 
array contain integer data. In this case, the array can have any 
number of elements after array (2). These elements must be numbered 
sequentially, starting at array (3}. All the elements contain integers. 
Each integer represents a longword of data. To determine how many 
longwords are being passed, an application can determine the length of 
the array and subtract 2 to allow for elements array (0} and array (1). 
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buffer 

The buffer containing the information to be sent to the requesting 
application as the response to the global selection information request. 

If you specify a buffer, VAXTPU converts the buffer to a string, converts 
line breaks to line feeds, and inserts padding blanks before text to fill any 
unoccupied space before the left margin. 

range 

The range containing the information to be sent to the requesting 
application as the response to the global selection information request. 

If you specify a range, VAXTPU converts the buffer to a string, converts 
line breaks to line feeds, and inserts padding blanks before and after text 
to fill any unoccupied space before the left margin. 

string 

The string containing the information to be sent to the requesting 
application as the response to the global selection information request. 
VAXTPU sends the information in string format. 

integer 

An integer whose value is to be sent to the requesting application as the 
response to the global selection information request. VAXTPU sends the 
information in integer format. 

NONE 

A ke5rword indicating that no information about the global selection is 
available. 

DESCRIPTION 

WRITE_GLOBAL_SELECT is valid only inside a routine that responds to 
requests for information about a global selection. 

The parameter specifies the data to supply to the requesting appUcation. 

If you specify NONE, VAXTPU informs the requesting application that 
no information is available. Note, however, that for any case in which a 
routine omits a WRITE_GLOBAL_SELECT statement, by default VAXTPU 
informs the requesting application that no information is available. 

Call WRITE_GLOBAL_SELECT no more than once during the execution 
of a global selection read routine. VAXTPU signals TPU$_INVBUILTIN if 
you attempt to call this routine more than once. 

SIGNALED 

ERRORS 

TPU$_BUILTININV WARNING WRITE_GLOBAL_SELECT has 

been used more than once in the 
same routine. 

TPU$_TRUNCATE WARNING VAXTPU has truncated characters 

from the data written because 


you specified a buffer or range 
containing more than 65,535 
characters. 


7-547 









VAXTPU Built-In Procedures 

WRITE GLOBAL SELECT 


EXAMPLE 

WRITE GLOBAL 


TPU$JNVPARAM 

ERROR 

One of the parameters was 
specified with data of the wrong 
type. 

TPU$_NORETURNVALUE 

ERROR 

WRITE_GLOBAL_SELECT cannot 
return a value. 

TPU$_REQUIRESDECW 

ERROR 

You can use the WRITE 
GLOBAL_SELECT built-in only 
if you are using DECwindows 
VAXTPU. 

TPU$_TOOFEW 

ERROR 

Too few arguments passed to 
the WRITE_GLOBAL_SELECT 
built-in. 

TPU$_TOOMANY 

ERROR 

Too many arguments passed to 
the WRITE_GLOBAL_SELECT 
built-in. 


SELECT (this_range); 

This statement sends the contents of the range this_range to the 
requesting application. 

For an example of a procedure using the WRITE_GLOBAL_SELECT 
built-in, see Example B-11. 
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The following VAXTPU procedures are included as samples of how to use 
VAXTPU to perform certain tasks. These procedures merely show one way 
of using VAXTPU; there may be other, more efficient ways to perform the 
same task. Make changes to these procedures to accommodate your style 
of editing. 

For these procedures to compile and execute correctly, you must make 
sure that there are no conflicts between these sample procedures and 
your interface. The following types of procedures are contained in this 
appendix: 

1 Line-mode editor 

2 Translation of control characters 

3 Restoring terminal width before exiting from VAXTPU 

4 DCL command procedure to run VAXTPU from a subprocess 


Line-Mode Editor 


The following example shows a portion of an editing interface that uses 
linft mode rather than screen displays for editing tasks. This mode of 
editing can be used for batch jobs, or for runmng VAXTPU on terminals 
that do not support screen-oriented editing. 


Portion of a line mode editor for VAXTPU 

Invoked from DCL with: EDIT/TPU/NODISPLAY/NOSECTION/COM=linemode.tpu file 


"file_name’') ; ! Set up main 

input_file); ! buffer from input 


input_file := GET_INFO (COMMAND_LINE, 
main_buffer := CREATE_BUFFER ("MAIN", 
POSITION (BEGINNING__OF (main___buf fer) ) ; 


! file 


! Continuously loop until QUIT 


LOOP 


cmd := READ_LINE ("*"); 

IF cmd = "" 

THEN 

cmd_char := "N"; 

ELSE 

cmd_char := SUBSTR (cmd, 1, 1); CHANGE_CASE (cmd_char, UPPER); 
ENDIF; 

CASE cmd char FROM "I" TO "T" ! Only accepting I,L,N,Q,T 
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!Top of buffer command 
["T"]: 

POSITION (BEGINNING_OF (CURRENT_BUFFER)); 

MESSAGE (CURRENT_LINE); 

!Next line command 
["N"]: 

MOVE_HORIZONTAL (-CURRENT_OFFSET); 

MOVE_VERTICAL (1); 

MESSAGE (CURRENT_LINE); 

!Insert text command 
["I"] : 

SPLIT_LINE; 

COPY_TEXT (SUBSTR (cmd, 2, 999)); 

MESSAGE (CURRENT_LINE); 

!List from here to end of file command 
["L"] : 

ml := MARK (NONE); 

LOOP 

MESSAGE (CURRENT_LINE) ; 

MOVE_VERTICAL (1) ; 

EXITIF MARK (NONE) = END_OF (CURRENT_BUFFER); 

ENDLOOP; 

POSITION (ml); 

SQUIT 

["Q"]: 

QUIT; 

[INRANGE,OUTRANGE]: 

MESSAGE ("Unrecognized command - enter I,L,N,Q or T"); 

ENDCASE; 

ENDLOOP; 


A.2 Translation of Control Characters 

The following procedures are examples of how to display control characters 
in a meaningful way. This is accomplished by translating the buffer to a 
different visual format and mapping this new form to a window. On the 
VT300 series and VT200 series of terminals, control characters are shown 
as reverse question marks. On the VTIOO series of terminals, they are 
shown as rectangles. 

! This procedure performs the substitution of meaningful characters 
! for the escape or control characters. 

I 

PROCEDURE translate__controls (char_range) 

LOCAL 

replace_text; 

I 

! If the translation array is not yet set up, then do it now. The elements 
! that we do not initialize will contain the value TPUK_UNSPECIFIED. They are 
! characters that TPU will display meaningfully. 

IF translate_array = TPU$K_UNSPECIFIED 
THEN 
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translate_array 

translate_array 

translate_array 

translate_array 

translate_array 

translate_array 

translate_array 

translate_array 

translate_array 

translate_array 

translate_array 

translate_array 

translate_array 

translate_array 

translate_array 

translate_array 

translate_array 

translate_array 

translate_array 

translate_array 

translate_array 

translate_array 

translate_array 

translate_array 

translate_array 

translate_array 

translate_array 

ENDIF; 


:= CREATE_ARRAY {32, 0); 
{1} := '<SOH>'; 

{2} := '<STX>'; 

{3} := '<ETX>'; 

{4} := '<EOT>'; 

{5} := '<ENQ>'; 

{6} := '<ACK>'; 

{7} := '<BEL>'; 

{8} := '<BS>'; 

{14} := '<S0>'; 

{15} := '<SI>'; 

{16} := '<DLE>'; 

{17} := '<DC1>'; 

{18} := '<DC2>'; 

{19} := '<DC3>'; 

{20} := '<DC4>'; 

{21} := '<NAK>'; 

{22} := '<SYN>'; 

{23} := '<ETB>'; 

{24} := '<CAN>'; 

{25} := '<EM>'; 

{26} := '<SUB>'; 

{27} := '<ESC>'; 

{28} := '<FS>'; 

{29} := '<GS>'; 

{30} := '<RS>'; 

{31} := '<US>'; 


! The range *must* be a single character long 

IF LENGTH (char_range) <> 1 
THEN 

RETURN 0; 

ENDIF; 

! Find the character 

replace_text := translate_array {ASCII (STR (char__range))}; 

! If we got hack a value of TPU$K_UNSPECIFIED, TPU will display the character 
! meaningfully 

IF replace_text = TPU$K_UNSPECIFIED 
THEN 

RETURN 0; 

ENDIF; 

I 

! Erase the range and insert the new text 

I 

ERASE (char_range); 

COPY_TEXT (replace__text) ; 

RETURN 1; 

ENDPROCEDURE; 

j 

! This procedure controls the outer loop search for the special 
! control characters that we want to view. 

j 

PROCEDURE view controls (source_buffer) 
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CONSTANT 


ctrl_char str 
ASCII 

(0) 

+ 

ASCII 

ASCII 

(4) 

+ 

ASCII 

ASCII 

(8) 

+ 

ASCII 

ASCII 

(12) 

+ 

ASCII 

ASCII 

(16) 

+ 

ASCII 

ASCII 

(20) 

+ 

ASCII 

ASCII 

(24) 

+ 

ASCII 

ASCII 

(28) 

+ 

ASCII 


LOCAL 

ctrl__char_pattern, 
ct r l_char__range; 


(1) 

+ 

ASCII 

(2) 

+ 

ASCII 

(3) 

+ 

(5) 

+ 

ASCII 

(6) 

+ 

ASCII 

(7) 

+ 

(9) 

+ 

ASCII 

(10) 

+ 

ASCII 

(11) 

+ 

(13) 

+ 

ASCII 

(14) 

+ 

ASCII 

(15) 

+ 

(17) 

+ 

ASCII 

(18) 

+ 

ASCII 

(19) 

+ 

(21) 

+ 

ASCII 

(22) 

+ 

ASCII 

(23) 

+ 

(25) 

+ 

ASCII 

(26) 

+ 

ASCII 

(27) 

+ 

(29) 

+ 

ASCII 

(30) 

+ 

ASCII 

(31) 

r 


Create the translation buffer and window, if necessary 


IF translate_buffer = TPU$K_UNSPECIFIED 
THEN 

translate_buffer := CREATE_BUFFER ("translation"); 
SET (NO_WRITE, translate_buffer); 

ENDIF; 

IF translate_window = TPU$K_UNSPECIFIED 
THEN 

translate_window := CREATE_WINDOW (1, 10, ON); 
ENDIF; 

Make a copy of the buffer we are translating 

ERASE (translate_buffer); 

POSITION (translate_buffer); 

COPY_TEXT (source_buffer); 


! Search for any control characters and translate them. If a control character 
! is not found, SEARCH_QUIETLY will return a 0. 

I 

ctrl_char__pattern := ANY (ctrl_char_str) ; 

POSITION (BEGINNING_OF (translate_buffer)); 

LOOP 

ctrl_char_range := SEARCH__QUIETLY (ctrl_char_pattern, FORWARD); 

EXITIF ctrl_char_range = 0; 

POSITION (ctrl_char_range); 

j 

! If we did not translate the character, move past it 

IF NOT translate_controls (ctrl_char__range) 

THEN 

MOVE_HORIZONTAL (1); 

ENDIF; 

ENDLOOP; 

j 

! Now display what we have done 

I 

POSITION (BEGINNING_OF (translate_buffer)); 

MAP (translate_window, translate__buffer) ; 

ENDPROCEDURE; 
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A.3 Restoring Terminal Width Before Exiting from VAXTPU 



Restoring Terminal Width Before Exiting from VAXTPU 

The following procedure compares the current width of the screen with 
the original width. If the current width differs from the original width, 
the procedure restores each window to its original width. The screen is 
refreshed so that information is visible on the screen after you exit from 
VAXTPU. When all of the window widths are the same, the physical screen 
width is changed. 

PROCEDURE user__restore_screen 
LOCAL 

original__screen_width, 

temp_w; 

original_screen__width := GET_INFO (SCREEN, "original_width"); 

IF original_screen_width <> GET___INFO (SCREEN, "width") 

THEN ” 

temp_w := get_info(windows,"first"); 

LOOP 

EXITIF temp__w = 0; 

SET (WIDTH, temp_w, original_screen__width) ; 

temp_w := GET_INFO (WINDOWS, "next"); 

ENDLOOP; 

REFRESH; 

ENDIF; 

ENDPROCEDURE; 

! Define the key combination CTRL/E to do an exit which 
! restores the screen to its original width, repaints 
! the screen, and then exits. 

DEFINE KEY ("user_restore_screen;EXIT", CTRL_E_KEY); 


A.4 Running VAXTPU from a Subprocess 

The following DCL command procedure shows one way of running 
VAXTPU from a subprocess. It also shows how to move to or from the 
subprocess. 

I 

!DCL command procedure to run VAXTPU from subprocess 

I 

!Put $ e = "@keptedit" 

!in your login.com. This spawns the editor the first time 
land attaches to it after that. I have defined a key to be 
!"attach" so it always goes back to the parent. 



A-5 









Sample VAXTPU Procedures 

A.4 Running VAXTPU from a Subprocess 


I $ tt = f$getdvi ("sys $ command”, "devnam") - ” »» - »•.»« 

$ edit_name = "Edit_” + tt ~ “ 

$ priv_list = f$setprv("NOWORLD, NOGROUP") 

$ pid = 0 
$10$: 

$ proc = f$getjpi(f$pid(pid), "PRCNAM") 

$ if proc .eqs. edit_name then goto attach 
$ if pid .ne. 0 then goto 10$ 

$spawn: 

$ priv_list = f$setprv(priv_list) 

$ write sys$error "[Spawning a new Kept Editor]" 

$ define/nolog sys$input sys$command: 

$ tl = f$edit(pi + " " + p2 + " " + p3 + " " + p4 + " " 

+ p5 + " " + p6 + " " + p7 + " " + p8,"COLLAPSE") 

$ spawn/process=""edit_name'" /nolog edit/tpu 'tl' 

$ write sys$error "[Attached to DCL in directory ''f$env("DEFAULT")']" 

$ exit 

$attach: 

$ priv_list = f$setprv(priv_list) 

$ write sys$error "[Attaching to Kept Editor]" 

$ define/nolog sys$input sys$command: 

$ attach "'' edit__name'" 

$ write sys$error "[Attached to DCL in directory ''f$env("DEFAULT")']" 
$ exit 
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Using DECwindows VAXTPU Buiit-ins 

You can use the DECwindows VAXTPU built-in procedures in many ways. 
However, you may find it useful to look at sample procedures showing 
how other programmers have used some of the DECwindows VAXTPU 
built-ins. Therefore, this appendix presents a number of procedures using 
DECwindows built-ins. 

The following example procedures are contained in this appendix: 

1 Displa 3 dng a Dialog Box 

2 Creating a “Mouse Pad” 

3 Implementing an EDT-Style APPEND Command 

4 Testing and Returning a Select Range 

5 Resizing Windows 

6 Unmapping Saved Windows 

7 Mapping Saved Windows 

8 Handling Callbacks from a Scroll Bar Widget 

9 Implementing the COPY SELECTION Operation 

10 Reactivating a Select Range 

11 Implementing the DECwindows COPY SELECTION Operation from 
EVE to Another Application 

Most of the procedures are drawn from the code implementing the 
Extensible VAX Editor (EVE). Some have been modified to make them 
easier to understand. 

You can see all the code used to implement EVE by looking at the files in 
the directory pointed to by the logical name SYS$EXAMPLES. To see a 
directory of the files available, type the following command from the DCL 
command line: 

$ DIR SYS$EXAMPLES:EVE$*.* 

These files contain procedures using many of the VAXTPU built-ins. 



Displaying a Dialog Box 

Example B-1 illustrates one of the ways a layered application can use 
the CONVERT built-in. This procedure is a modified version of the 
EVE procedure eve$$mb2_dispatch. You can find the original version 
in SYS$EXAMPLES:EVE$MOUSE.TPU. For more information about 
using the files in SYS$EXAMPLES as examples, see Section B.l. 
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B.2 Displaying a Dialog Box 


The procedure displays EVE’s selection pop-up menu on the screen if the 

procedure is called while a select range or found range is active. 

This example uses the following global variables and procedures: 

• EVE$CALLBACK_DISPATCH — The procedure that EVE uses to 
dispatch all widget callbacks. 

• EVE$X_FOUND_RANGE — A global variable that holds the range for 
the last text found. If there is not currently a found range, it is set to 
zero. 

• EVE$X_SELECT_POPUP — A global variable that holds the pop-up 
menu widget used when a selection is present. 

• EVE$X^SELECT_POPUP^HEIGHT - A global variable that holds 
the height of the selection pop-up menu. 

• EyE$X__SELECT_POPUP_WIDTH — A global variable that holds the 
width of the selection pop-up menu. 

• EVE$X_SELECT_POSITION — A global variable that holds the start 
marker for the select range. If there is not currently a selection, it is 
set to zero. 

Example B-1 EVE Procedure That Displays a Selection Dialog Box 


PROCEDURE eve$$mb2_dispatch 

local status, 

the_window, 
temp_array, 
the__widget, 
x__l, 

X2, 

widget_hierarchy, 

y_2; 


OIF (LOCATE_MOUSE (the_window, x_l, y 1) <> 0) 
THEN “ 

@ CONVERT (the_window, CHARACTERS, x_l, y_l, 
DECW_ROOT_WINDOW, COORDINATES, 

X2, y_2); 


IF (eve$x_select_position <> 0) OR ! A selection exists 

(eve$x_found_range <> 0) » a found range exists 

THEN 

IF GET_INFO (eve$x_select_popup, "type") <> WIDGET 
THEN 

widget_hierarchy := SET (DRM_HIERARCHY, "EVE$WIDGETS"); 


(continued on next page) 
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B.2 Displaying a Dialog Box 


Example B-1 (Cent.) EVE Procedure That Displays a Selection Dialog Box 


eve$x_select_j)opup := CREATE__WIDGET (”SELECT_POPUP", 

widget_hierarchy, 

♦ SCREEN, 

"eve$callback_dispatch'') ; 

ENDIF; 

! Get width and height of this pop-up menu if needed 

O temp_array := CREATE_ARRAY; 

temp__array {eve$dwt$c_width} := 0; 
temp_array {eve$dwt$c_height} := 0; 

status := GET_INFO (eve$x__select_popup, ”WIDGET_INFO", temp_array); 
eve$x_select_popup__width := temp_array {eve$dwt$c_width}; 
eve$x select popup_height := temp_array {eve$dwt$c__height}; 

! Calculate position for upper left corner of 
! dialog box and set the appropriate resources of the widget 

temp_a rray := CREATE_ARRAY; 

temp array {eve$dwt$c_nx} := X2 - (eve$x_select__popup_width/2); 

IF temp_array {eve$dwt$c_nx} < 1 
THEN 

temp_array {eve$dwt$c_nx} := 1; 

ENDIF; 

temp_array {eve$dwt$c_ny} y_2 - (eve$x_select^opup_height/2) ; 

IF temp_array {eve$dwt$c_ny} < 1 
THEN 

temp_array {eve$dwt$c_ny} := 1; 

ENDIF; 

@ SET (WIDGET, eve$x_select__popup, temp_array) ; 

@ MANAGE__WIDGET (eve$x_select_popup) ; 

ENDIF; 

ENDIF; 

RETURN (TRUE); 

ENDPROCEDURE; 


O The return value from the LOCATE_MOUSE built-in procedure 
indicates whether the pointer cursor is in the window. LOCATE_ 
MOUSE also returns the row, column and window where the pointer 
cursor is located. The coordinates returned refer to a system whose 
origin is in the upper left comer of the VAXTU window. 

@ This clause converts the pointer cursor location from a system whose 
origin is at the upper left comer of the VAXTPU window to a system 
whose origin is at the upper left comer of the DECwindows root 
window. For more information about the difference between VAXTPU 
windows and DECwindows windows, see Chapter 4. 

® SET (DRM_HIERARCHY, file_spec) allows you to tell VAXTPU which 
XUI Resource Manager hierarchy to use. An XUI Resource Manager 
hierarchy is a set of widgets implementing a user interface. For 
example, EVE’s menu bar and menu widgets compose an XUI Resource 
Mamager hierarchy. 


B-3 










B.3 


Sample DECwindows VAXTPU Procedures 

B.2 Displaying a Diaiog Box 


EVE uses the XUI Resource Manager hierarchy stored in the file 
EVE$WIDGETS.UID. If you are extending EVE, you need not set the 
hierarchy again. 

VAXTPU allows you to use multiple XUI Resource Manager 
hierarchies. If you want to use a second hierarchy (defined in a file 
other than EVE$WIDGETS.UID), use the SET (DRM_HIERARCHY) 
statement before using the CREATE_WIDGET statement. 

O GETJNFO (widget, "widget_info", array) allows you to fetch 

information about a widget. The index of each element of the array 
must be a string naming the resource whose value you want to fetch. 
For more information about what resources a given widget supports, 
see the VMS DECwindows Toolkit Routines Reference Manual. 

© SET (WIDGET, widget, array) allows you to set a widget’s resource 
values. The index of each element of the array must be a string 
naming the resource whose values you want to set. For more 
information about what resources a ^ven widget supports, see the 
VMS DECwindows Toolkit Routines Reference Manual. 

© MANAGE_WIDGET reahzes the widget and makes it visible on the 
screen. 


Creating a “Mouse Pad” 

Example B-2 shows how to use the variant of CREATE_WIDGET 
that calls the XUI Toolkit low-level creation routine. The module in 
Example B-2 creates a screen representation of a keypad. Instead of 
pressing a keypad key, a user can click on the widget representing the 
key. 

Example B—2 Procedure That Creates a “Mouse Pad” 


SAMPLE.TPU 
++ 

Table of Contents 
SAMPLE.TPU 

Procedure name Description 


s amp1e_s amp1e_modu1 e_ident 
sample_sample_module_init 
eve_mou s e__pad 
sample_key_def 
sample_key__dispatch 
s amp 1 e_r o w__t o__p i x 
s amp 1 e_c o l_t o_p i X 
s amp 1 e__key_h e i gh t 
sample_key_width 


Ident. 

Initializes the module. 

Implements the user command DISPLAY MOUSE PAD. 
Creates a mouse pad "key" push button. 

Handles push button widget callbacks. 

Converts a row number to pixels. 

Converts a column number to pixels. 

Converts y dimension from rows to pixels. 
Converts x dimension from columns to pixels. 


(continued on next page) 
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B.3 Creating a “Mouse Pad” 


Example B-2 (Cent.) Procedure That Creates a “Mouse Pad” 


! This module layers a "mouse pad" on top of VAXTPU. The mouse pad 
! is implemented by creating a dialog box widget that is the parent of a group 
! of push button widgets depicting keypad keys. The resulting 
! "mouse pad" is a screen representation of a keypad. The user can 
! click on a push button to execute the same function that would be 
! executed by pressing the corresponding keypad key. The module uses 

! the key map list mapped to the current buffer to determine what 

! code to execute when the user clicks on a given push button. To 
! use a different key map, substitute a string naming the desired 
! key map for the null string assigned to "sample_k_keymap". 

! This module can be used with the EVE section file 

! or with a non-EVE section file. 

I 

! This module uses the variant of CREATE_WIDGET that calls the XUI 
! Toolkit low-level creation routine. 


PROCEDURE sample_sample__module_ident ! This procedure returns 

RETURN "VOl-001"; • Ident. 

ENDPROCEDURE; 

PROCEDURE sample_sample_module_init ! Module initialization. 

ENDPROCEDURE; 

1 VAXTPU Declarations for XUI Toolkit constants 

! Use these constants as arguments to the DEFINE_WIDGET built-in. 

! The strings are the symbols that evaluate to the 
! widget class records for the DECwindows widgets. 

CONSTANT 

sample_k_labelwidgetclass := "labelwidgetclassrec", 
sample_k_dialogwidgetclass := "dialogwidgetclassrec", 
sample_k_pushbuttonwidgetclass := "pushbuttonwidgetclassrec"; 

! Use these constants, which are XUI Toolkit 

! resource name strings, as callback reasons, resource values, or 
! arguments to the CREATE___WIDGET built-in. 

CONSTANT 

sample_k_cstyle := "style", 
sample__k_modeless := 2, 
sample_k_nunits := "units", 
sample_k_pixelunits := 1, 
sample_k_ntitle := "title", 
s amp1e_k_nx := "x", 
s amp1e_k_ny := ”y"/ 
sample_k_nheight := "height", 
sample_k__nwidth := "width", 
sample__k_nlabel := "label", 

sample_kt__nactivate_callback := "activateCallback", 
sample”kt_nborderwidth := "borderWidth",. 
sample_kt_nconformToText := "conformToText", 
sample_k_cractivate := 10; 


(continued on next page) 
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B.3 Creating a “Mouse Pad” 



Example B-2 (Cont.) Procedure That Creates a “Mouse Pad” 


! These constants are intended for use only in this sample module 
! because their values are specific to the mouse pad application. 

CONSTANT 

sample__k_x_pos := 500, ! Screen position for mouse pad. 

sample___k__x_pos := 500, 

sample_k__keypad_border := 5, ! Width of border between keys and edge. 

sample_k_key_height := 30, ! Key dimensions, 

samp 1 e__k_key_width : = 60, 

sample_k_button_border__frac := 3, ! Determines spacing between keys. 
sample_k_overall_height ;= (sample_k_key_height * 5) 


+ ( (sample_k_key_height 


/ sample__k__button_border__frac) * 5) 
+ sample_k_keypad_border. 



sample_k_overall width 


(samp1e_k_key_width * 4) 
+ ( (sample_k__key_width 


/ sample_k_button_border__frac) * 4) 
+ sample__k_keypad__border. 


s amp 1 e_k_ke ymap : = ' ' 


! If this constant has a null string 
! as its value, the program uses the 
! current key map list to determine what 
! code to execute when the user 
! clicks on a given push button. 



sample__kjpad__title := "Sample mouse pad", ! Title of the mouse pad. 


sample_k_closure ;= 


! Not currently used. 


PROCEDURE eve mouse_pad 
ON ERROR 


Implements a user-created command MOUSE PAD 
that the user can invoke from within EVE. 


[TPU$__CONTROLC] : 

eve$learn__abort; 
ABORT; 


ENDON ERROR 


! Checks whether the dialog box widget class has already been defined. 
! If not, defines the dialog box widget class and creates a widget 
! instance to be used as the "container" for the mouse pad. 

IF GET_INFO (sample_x__dialog_class, 'type') <> INTEGER 
THEN 

s amp 1 e_x_di a 1 og_c lass 



o 


DEFINE_WIDGET_CLASS (sample_k__dialogwidgetclass, 

"dwt$dialog__box_popup_create") ; 


ENDIF; 


(continued on next page) 
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B.3 Creating a “Mouse Pad” 


Example B-2 (Cent.) Procedure That Creates a “Mouse Pad” 


©sample x keypad := CREATE_WIDGET (sample_x_dialog_class, "Keypad", SCREEN, 

■" "MESSAGE('CALLBACK activated')", 

"sainple__k_closure ", 

sample_k__cstyle, sample__k__modeless, 
sample_k___nunits, sample__k_pixelunits, 
s amp 1 e_k_nt i 11 e, s amp 1 e_k_pad__t i11 e, 
s amp 1 e__k_nhe i ght, s amp 1 e__k__ove ra 1 l_he i ght, 
sample_k_nwidth, sample__k_overall__width, 

s amp 1 e__k_nx, s amp 1 e__k_x_po s, 
sample_k_ny, sample__k_y^os) ; 


! Checks whether the push button widget class has already been defined 
! and, if not, defines the class. 


IF GET_INFO (sample_x_pushbutton_class, 'type') <> INTEGER 
THEN ” 

s amp 1 e__x_pu s hbut t on_c lass 

:= DEFINE__WIDGET_CLASS ( samp le_k_pushbuttonwidgetclass, 

"dwt$push__button_create") ; 

ENDIF; 


! This statement 
! using the built_in 
! DEFINE_WIDGET_CLASS 
! defines the 
! class of the 
! push button 
! widgets. 


! Initializes the array that the program passes repeatedly 
! to the procedure "sample_key_def". 


s amp 1 e_x__a11 r ibut e s : = CREATE_ARRAY; 

sample”x__attributes {sample_k_nactivate_callback} := 0; 
sample_x_attributes {sample_k_nborderwidth} : = _ 2; 
sample x__pad program ;= COMPILE ("sample_key_dispatch"); 

! Creates and manages all the "keys" in the mouse pad. The procedure 
! "sample_key__def" returns a variable of type widget, so you can use the 
! returned value as an argument to the built-in MANAGE_WIDGET. 


0 MANAGE^WIDGET 


(s amp1e_key_de f 
sample_key__def 
s amp 1 e__k e y_de f 
sample_key_def 
s amp 1 e_ke y_de f 
sample_key__def 
s amp 1 e_ke y_de f 
sample_key_def 
s amp 1 e_ke y_de f 
sample_key_def 
sample_key_def 
sample__key_def 
sample__key_def 
sample_key_def 
s amp 1 e_key_de f 
s amp 1 e_key_de f 

s amp 1 e_k e y_de f 
s amp 1 e__k e y_de f 


("PFl", 0, 0, 1, 1, sample_x_pad_program), 

("PF2", 1, 0, 1, 1, sample_x__pad_program) , 

("PF3", 2, 0, 1, 1, sample_x_pad__program) , 

("PF4", 3, 0, 1, 1, sample__x_j3ad_j5rogram) , 

("KP7", 0, 1, 1, 1, sample_x_pad_program), 

("KPS", 1, 1, 1, 1, sample_x_pad_program), 

("KP9", 2, 1, 1, 1, sample_x_pad__program) , 

("-", 3, 1, 1, 1, sample_xjpad_j3rogram, "minus") 

("KP4", 0, 2, 1, 1, sample_x_pad_j>rogram), 

("KPS", 1, 2, 1, 1, sample_x_pad__program) , 

("KP6", 2, 2, 1, 1, sample_x_pad_program), 

(",", 3, 2, 1, 1, sample_x_pad_program, "comma") 

("KPl", 0, 3, 1, 1, sample_x_pad_program), 

("KP2", 1, 3, 1, 1, sample__x__pad__program) , 

("KP3", 2, 3, 1, 1, sample__x__pad__program) , 

("Enter", 3, 3, 2, 1, sample__x_pad_j)rogram, 
"enter"), 

("KPO", 0, 4, 1, 2, sample__x_pad_program) , 

(".", 2, 4, 1, 1, sample_x_pad_j5rogram, 

"period")); 


sample x shift_was_last := FALSE; ! The program starts out assuming that 

"" ! no GOLD key has been pressed. 


(continued on next page) 
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8.3 Creating a “Mouse Pad” 


Example B-2 (Cent.) Procedure That Creates a “Mouse Pad” 


OMANAGE_WIDGET (sample_x_keypad); ! This statement displays the 

! resulting mouse pad. 

RETURN (TRUE); 

ENDPROCEDURE; ! End of procedure eve_mouse_pad. 


PROCEDURE sample__key_def 

(the_legend, 
the_row, the_col, 

the_width, the__height, 
the_pgm; 

the_string); 


! Creates a mouse pad "key" push button 
! widget. 

What characters to show on the push button label. 

Location of the key in relation to the parent 
widget's upper left corner. 

Dimensions of the key. 

Program to use as the callback routine; used 
as a parameter to the CREATE_WIDGET built-in. 

The string representation of the name 
of a key if the key name is not going 
to be the same as the legend (as in 
the case of the comma). Specify the null 
string if the key name and the legend are 
the same. 


IF GET__INFO (the_string, 'type') = UNSPECIFIED 
THEN 

the__string := the_legend; ! Determines whether the optional parameter 

! the string is provided. 

ENDIF; “ 


RETURN CREATE__WIDGET (sample_k__pushbutton_class, "Key", sample_x_keypad, 

the__pgm, 

(sample_k_keymap + ' ' + the_string) , 
s amp 1 e_x__a 11 r i bu t e s, 
sample_kt_nconformToText, 0, 
sample_k_nlabel, the__legend, 

sample__k_nheight, sample_key_height (the_width) , 
sample__k_nwidth, sample_key__width (the__height) , 
sample__k_nx, sample_col_to__pix (the_row) , 
sample_k__nx, sample__row_to_pix (the_col) ) ; 

ENDPROCEDURE; ! End of the procedure "sample_key def". 


PROCEDURE sample__key___dispatch 
LOCAL status, 

blank_index, 

temp___array, 

a_shift__key, 

the__key, 

gold_key; 


! Handles push button widget callbacks. 

! Variable to contain the return value from 
! GET^INFO (WIDGET, "callback__parameters",) . 

! Position of the blank space in the tag string. 

! Holds callback parameters. 

! The SHIFT key in the current key map list. 

! A string naming a key. 

! Name of the GOLD key. 


(continued on next page) 
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B.3 Creating a “Mouse Pad” 


Example B-2 (Cent.) Procedure That Creates a “Mouse Pad” 


ON_ERROR 

[TPU$_CONTROLC]: 

eve $ 1 ea rn__abo rt; 

ABORT; 

ENDON__ERROR 

©status := GET_INFO (widget, "callback_parameters", temp_array) ; 
$widget ;= temp_array {'widget'}; 

$widget_tag := temp_array {'closure'}; 

$widget_reason := temp_array {'reason_code'}; 

®the_key := EXECUTE ("RETURN (KEY_NAME (" + $widget_tag + ”))"); 
gold_key := GET^INFO (eve$current_key_map_list, "shift_key"); 

IF the_key = gold__key 
THEN 

sample_shift_was__last := TRUE; ! User pressed Gold Key 

ELSE 

IF sample__shift_was__last 
THEN 

the_key ;= KEY_NAME (the_key, SHIFT_KEY); 

ENDIF; 

CASE $widget_reason 

[sample_kt_cractivate]: 

EXECUTE (the_key); 

[OTHERWISE]: 

eve__show_key (the_key) 

ENDCASE; 

sample_shift__was__last := FALSE; 

ENDIF; 

RETURN; 

ENDPROCEDURE; ! End of the procedure "sample__key__dispatch”. 


! These procedures implement position and 
! size calculations for the push button widgets. 

PROCEDURE sample__row__to__pix (row) ! Converts a row number to the 

! pixel-based measuring system. 

RETURN sample__k__keypad_border + 

(row * (sample_k_key_height + (sample_k__key_height 

/ sample_k_button_border_frac) ) ) ; 
ENDPROCEDURE; ! End of the procedure ”sample_row_to_pix". 

PROCEDURE sample_col_to__pix (col) ! Converts a column number to the 

! pixel-based measuring system. 

RETURN sample_k_keypad__border + 

(col * ( (sample__kt__key__width + sample_kt__key__width) 

/ sample_kt_button__border__f rac ) ) ; 

ENDPROCEDURE; ! End of the procedure "sample_col_to_pix". 


(continued on next page) 
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B.3 Creating a “Mouse Pad” 


Example B-2 (Cent.) Procedure That Creates a “Mouse Pad” 


PROCEDURE sample_)cey_height (given_height) ! Converts the y dimension 

! from rows to pixels. 

IF given_height = 1 
THEN 

RETURN sample__k__key_height; 

ELSE 

RETURN ((sample__k_key_height * given_height) 

+ (sample_k_key_height / sample__k__button__border_frac) 

* (given_height - 1)); 

ENDIF; 

ENDPROCEDURE; ! End of the procedure "sample_key_height". 

PROCEDURE sample_key_width (given_width) ! Converts the x dimension 

! from rows to pixels. 

IF given__width = 1 
THEN 

RETURN sample_k__key_width; 

ELSE 

RETURN ((sample_k_key_width * given_width) 

+ (sample_k__key__width / sample_k_button__border__frac) 

* (given_width -1)); — 

ENDIF; 

ENDPROCEDURE; ! End of the procedure ''sample__key width". 


O When you create widgets directly in VAXTPU (that is, without using 
the XUI Resource Manager to manipulate widgets defined in a UIL 
file) you must define each class of widget. For example, a widget can 
belong to the push button, dialog box, menu, or another similar class 
of widget. The DEFINE_WIDGET_CLASS built-in procedure tells 
VAXTPU the widget class name and creation entry point for the Haag 
of widget. DEFINE_WIDGET_CLASS also returns a widget ID for 
that widget class. Define a widget class for each widget only once in a 
VAXTPU session. 

@ The CREATE_WIDGET built-in allows you to create an instance of a 
widget for which you have a widget ID. An instance is one occurrence 
of a widget of a given class. For example, EVE has meuiy menu 
widgets, each of which is an instance of a menu widget. 

This example creates a dialog box widget to contein the mouse pad. 

® Each of the keys of the mouse pad is managed. However, they do not 
become visible until their parent, the dialog box widget in variable 
SAMPLE_X_KEYPAD, is managed. 

O Managing a widget whose parent is visible causes that widget and all 
its managed children to become visible. 

@ GET_INFO (WIDGET, "callback_parameters", array) returns the 
callback information in the array parameter. For more information 
about using this built-in, see the built-in’s description in the VAXTPU 
Reference Section. 
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B.3 Creating a “Mouse Pad” 


© When each key widget of the mouse pad is created, the closure value 
for the widget is set to the string corresponding to the name of the 
key that the widget represents. This statement uses the EXECUTE 
built-in to translate the string into a key name. 

B.4 Implementing an EDT-Style APPEND Command 

Example B-3 shows one of the ways an application can use the GET_ 
CLIPBOARD built-in. This procedure is a modified version of the EVE 
procedure EVE$EDT_APPEND. You can find the original version in 
SYS$EXAMPLES:EVE$EDT.TPU. For more information about using the 
files in SYS$EXAMPLES as examples, see Section B.l. 

The procedure EVE$EDT_APPEND appends the currently selected text 
to the contents of the clipboard if the user has activated the chpboard, 
otherwise, the procedure appends the current selection to the contents of 
the Insert Here buffer. 

This example uses the following global variables and procedures from 
EVE: 

• EVE$MESSAGE — A procedure that translates the specified message 
code into text and displays the text in the Messages buffer. 

• EVE$$RESTORE_POSITION — A procedure that repositions the 
editing point to the location indicated by the specified window and 
marker. This procedure is for EVE internal use only. Do not call this 
procedure in a user-written procedure. 

• EVE$LEARN_ABORT — A procedure that aborts a learn sequence. 

• EVE$SELECTION — A procedure that returns a range containing the 
current selection. This can be the select range, the found range, or the 
text of the global selection. 

• EVE$$TEST_IF_M0DIFIABLE — A procedure that checks whether 
a buffer can be modified. This procedure is for EVE internal use only. 
Do not call this procedure in a user-written procedure. 

• EVE$X_DECWINDOWS_ACTIVE — A Boolean global variable that 
is true if VAXTPU is using DECwindows. If VAXTPU is not using 
DECwindows, the DECwindows features are not available. 

• EVE$$X_STATE_ARRAY — A global variable of type array describing 
various EVE flags and data. This variable is private to EVE and 
should not be used by user routines. 

• EVE$$EDT_APPEND_PASTE — Procedure that appends text to the 
Insert Here buffer. This procedure is for EVE internal use only. Do 
not call this procedure in a user-written procedure. 
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B.4 Implementing an EDT-Style APPEND Command 


Example B-3 EVE Procedure That Implements a Variant of the EOT APPEND Command 


PROCEDURE eve$edt append 

! Implements EVE's version of 
! the EDT APPEND command. 

LOCAL saved mark. 

! Marks the editing point at the 
! beginning of the procedure. 

remove_range, 

! Stores the currently selected text. 

old_string. 

! Stores the text that was in the clipboard. 

new_string. 

! Stores the old contents of the clipboard 
! plus the currently selected text. 

remove_status; 

! Indicates whether the selected text 
! should be removed. 


ON_ERROR 

[TPU$_CLIPBOARDNODATA]: 

eve$message (EVE$_NOINSUSESEL); 
eve$$restore_position (saved_mark); 
eve$learn_abort; 

RETURN (FALSE); 

[TPU$_CLIPBOARDLOCKED]: 

eve$message (EVE$_CLIPBDREADLOCK); 
eve$$restore_position (saved_mark); 
eve $1ea rn_abo rt; 

RETURN (FALSE); 

[TPU$_CONTROLC]: 

eve$$restore_position (saved_mark); 
eve$learn_abort; 

ABORT; 

[OTHERWISE]: eve$$restore_position (saved mark); 

eve$learn_abort; 

ENDON__ERROR; 


remove__range := eve$selection (TRUE) ; 

IF remove_range <> 0 

THEN 


o 


saved._mark := MARK (NONE) ; 

remove_status := eve$test_if_modifiable (GET_INFO (saved mark, 
IF eve$x_decwindows_active ~ 

THEN 

IF eve$$x_state_array {eve$$k clipboard) 

THEN 

old_string := GET_CLIPBOARD; 

string_range := old_string + str (remove_range); 
WRITE_CLIPBOARD ("", new_string); 


"buffer")); 


(continued on next page) 
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B.4 Implementing an EDT-Style APPEND Command 


Example B-3 (Cent.) EVE Procedure That Implements a Variant of the EOT APPEND Command 


IF remove_status 
THEN 

ERASE (remove__range) ; 
eve$message (EVE $__REMCL IP BOARD) ; 

ENDIF; 

ELSE 

eve$$edt__append_j>aste (remove_range, remove_status) ; 
ENDIF; 

ELSE 

eve$$edt_append__paste (remove_range, remove_status) ; 
ENDIF; 

POSITION (saved_mark) ; 
remove^range := 0; 

RETURN (TRUE); 

ENDIF; 

eve $1ea rn_abo rt; 

RETURN (FALSE); 

ENDPROCEDURE; 


O The GET_CLIPBOARD built-in procedure returns a copy of the text 
stored in the clipboard. Only data of type string can be retrieved from 
the clipboard. Any other data type causes VAXTPU to signal an error. 

@ The WRITE. CLIPBOARD built-in procedure stores data in the 
clipboard. The first parameter allows you to specify the label for 
this data. However, the clipboard currently supports only one entry at 
a time, so you can use any string for the first parameter. 


B.5 Testing and Returning a Select Range 

The code fragment in Example B-4 shows how a layered application 
can use GET_GLOBAL_SELECT. This code fragment is a portion of the 
EVE procedure EVE$SELECTION. You can find the original version in 
SYS$EXAMPLES:EVE$CORE.TPU. For more information about using the 
files in SYS$EXAMPLES as examples, see Section B.l. 

The procedure EVE$SELECTION returns a select range, found range, or 
global selection for use with EVE commands that operate on the select 
range. 

This example uses the following global variables and procedures from 
EVE: 

• EVE$MESSAGE — A procedure that translates the specified message 
code into text and displays the text in the message buffer. 

• EVE$LEARN_ABORT — A procedure that aborts a learn sequence. 
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B.5 Testing and Returning a Seiect Range 


• EVE$X_DECWINDOWS_ACTrVE — A Boolean global variable that 
is true if VAXTPU is using DECwindows. If VAXTPU is not using 
DECwindows, the DECwindows features are not available. 


Example B-4 EVE Procedure That Returns a Select Range 


PROCEDURE eve$selection ( 

do__me s s age s; 
found__range__arg^ 
global_arg, 
null_range_arg, 
cancel_arg) 

Return Values; range 

0 

NONE 
string 

LOCAL possible_selection, 
use_found_range, 
use_global, 
extend_null_range, 
cancel_range/ 

ON__ERROR 

[TPU$_SELRANGEZERO]: 

[TPU$_GBLSELOWNER]: 

eve$message (EVE$_NOSELECT); 
eve $1ea rn_abort; 

RETURN (FALSE); 

[OTHERWISE]: 

ENDON__ERROR; 


! Display error messages? 

! Use found range? (D=TRUE). 

! Use global select? (D=FALSE). 
! Extend null ranges? (D=TRUE). 
! Cancel selection? (D=TRUE). 

The selected range. 

There was no select range. 

There was a null range and 
null_range_arg is FALSE. 

Text of the global selection 
if "global_arg" is TRUE. 


! The procedure first tests whether it 
! has received a parameter directing 
! it to return a found range or global 
! selection if no select range has been 
! created by the user. 

IF GET_INFO (found_range_arg, "type”) = INTEGER 

THEN 

use_found_range ;= found range arg; 

ELSE “ ~ 

use__found__range := TRUE; 

ENDIF; 

IF GET_INFO (global_arg, "type") = INTEGER 

THEN 

use_global := global_arg; 

ELSE 

use__global := FALSE; 

ENDIF; 


(continued on next page) 
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B.5 Testing and Returning a Select Range 


Example B-4 (Cent.) 

EVE Procedure That Returns a Select Range 

I 

1 

! 

! In the code omitted from this example, 

! eve$selection returns the appropriate 
! range if the calling procedure has 
! requested the user's select range 
! or a found range. 

! If there is no found range or select 
! range, the procedure returns 
! the primary global selection 
! if it exists. 


IF use__global and eve$x_decwindows_active 
THEN 

possibl© S6l©ction i— GET_GLOBAL_SELECT (PRIMARY^ 

" "STRING"); 

IF GET_INFO (possible__selection, "type") = STRING 
THEN 

RETURN (possible_selection); 

ENDIF; 

ENDIF; 


RETURN (0); 

ENDPROCEDURE; 

! Indicates failure. 


O DECwindows allows you to designate more than one global selection. 
The two most common global selections are the primary and secondary 
selections. A global selection can be owned by only one DECwindows 
application at a time. 

The GET_GLOBAL__SELECT built-in returns the data for the 
requested selection in the requested format. If the requested selection 
is not currently owned by any application, or if the owner cannot 
return it in the requested format, then GET_GLOBAL__SELECT 
returns unspecified. 

If the selected information contains multiple records, the records are 
separated by the line-feed character (ASCII (10)). 
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B.6 Resizing Windows 

Example B-5 shows the procedure SAMPLE_NEW_SCREEN_SIZE, which 
manipulates visible windows when the user makes the screen smaller. 

It removes visible VAXTPU windows from the screen, starting at the 
bottom of the VAXTPU screen, until the combined length of the remaining 
windows is less than or equal to the new smaller screen size or until 
there is only one window left. (For more information about the difference 
between VAXTPU windows and DECwindows windows, see Chapter 4.) 

If only one window remains, the procedure adjusts the window to fit the 
screen. If two or more windows remain, the procedure adjusts the current 
window and the bottom window. 

The procedure uses the following variants of the built-in GET_INFO 
(window_variable): 

• GETJNFO (window_variable, "bottom") 

• GET_INFO (window_variable, "length") 

• GETJNFO (window_variable, "top") 

This example uses the following global variables and procedure from EVE: 

• EVE$GET_WINDOW — A procedure that returns the window 
associated with a niunber. The windows are numbered sequentially, 
from top to bottom. 

• EVE$X_NUMBER_OF_WINDOWS - A global variable that holds the 
count of the visible windows. 

• EVE$$GET_WINDOW_NUMBER - A procedure that returns a 
number for the current window. EVE associates a value with each 
window so EVE can save information about specific windows. This 
procedure is for EVE internal use only. Do not call this procedure in a 
user-written procedure. 

• EVE$$REMOVE_WINDOW — A procedure that removes a window 
from the screen. This procedure is for EVE internal use only. Do not 
call this procedure in a user-written procedure. 
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Example B-5 Procedure That Resizes Windows 


PROCEDURE sample_new_screen__size 

LOCAL overhead, 

new_screen_length, 

number, 

the__count, 

total__length, 

some__window, 

a_window, 

new__top, 

a_length, 

top_adjust, 

bottom__window, 

bottom_adjust; 


overhead ;== 2; ! This provides lines for the command window and message 

! window, assuming each window has a length of 1. 


O new__screen__length := get_info (SCREEN 
number := eve$$get__window__number; 

the count := eve$x_number_of_windows; 


'new_length"); 

! This sets "number” to be 
! the number of the current window. 

! This sets ”the_count" to 
! be the total number of 
1 visible windows. 


! The following lines determine the combined lengths of all 
! user-created windows visible on the screen, plus the lengths of the 
! command window and message window. 

total_length := overhead; 

the count := eve$x_number_of_windows; 

LOOP 

EXITIF the_count < 1; 

some window := eve$get__window (the_count) ; 

! "Some window” is the bottommost window not yet measured. 

total_length := total_length + 

GET_INFO (some_window, "length”, WINDOW); 

the_count := the__count - 1; 

ENDLOOP; 

! The following statements delete windows from the screen, starting 
1 with the bottommost window, until the sum of the lengths 
! of all remaining windows is less than or equal to the new screen 
! length. 

the_count := eve$x__number__of_windows; 

LOOP 

EXITIF the count <= 1; . ^ ^ 

a window := eve$get_window (the_count); ! This statement sets ”a_window to 

”■ ! be the bottommost 

! window not yet examined 
! in this loop. 


(continued on next page) 
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Example B-5 (Cont.) Procedure That Resizes Windows 

@ IF number > the count 


o 


THEN 

new_top := GET__INFO (a_window, "top”, WINDOW); 


ENDIF; 

IF number <> the_count ! If the current window is still 

! above the window to which you're 
! comparing it 

THEN 

a_length := GET__INFO (a_window, "length", WINDOW); 


! The following clause prevents the loop from deleting 
! the bottom window if the new screen length 
! is greater than or equal to the old screen length. 

IF new_screen_length > total_length 


! The following statement decreases "total_length" by the length 
! of the window being examined. 

THEN 

total_length := total__length - a_length; 

! The following statement removes the window 
! being examined. 

eve$$remove_window (the_count); 

ENDIF; 

EXITIF total_length <= new_screen__length; 

ENDIF; 

the__count := the_count - 1; ! Next time through the loop, the window 

! being examined will be the window 
! just above the window examined this time. 

ENDLOOP; 

IF eve$x_number_of_windows = 1 
THEN 

adjust_window (CURRENT__WINDOW, 

1 - get_info (CURRENT_WINDOW, "top", WINDOW), 
new_screen_length - overhead 

-get^info (CURRENT_WINDOW, "bottom", WINDOW)); 

ELSE 

! The following statements adjust the top of the current 
! window and the bottom of the bottom window, if needed, 

! to occupy the space left by deleting windows. 


(continued on next page) 
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Example B-5 (Cent.) Procedure That Resizes Windows 


IF new_top <> 0 
THEN 

top adjust := new top - GET__INFO (CURRENT_WINDOW, 

- "" "top”, WINDOW); 

ADJUST_WINDOW (CURRENT_WINDOW, top_adjust, 0); 

ENDIF; 

bottom_window ;= eve$get__window (eve$x_number_of_windows); 
bottom_adjust := new_screen_length - 
overhead - 

GET INFO (bottom_window, ! This statement using 

” "bottom", WINDOW); ! GET__INFO (window, "bottom") 

! calculates the amount 
! by which to adjust the 
! bottom of the bottom 
! window. 

ADJUST_WINDOW (bottom__window, 0, bottom_adjust); 

ENDIF; 

ENDPROCEDURE; ______ 

O GET_INFO (SCREEN "newjength") returns the size of the screen 
after a resize occurs. 

O GETJNFO (window, "length", WINDOW) returns the length of the 
window. 

0 Number is greater than the_count only when the current window is 
below the window to which you are comparing it. 

O GETJNFO (window, "top", WINDOW) returns the top line of the 
window. 

0 GETJNFO (window, "bottom", WINDOW) returns the line number of 
the last line in the window. 


B.7 Unmapping Saved Windows 

Example B-6 shows the procedure SAMPLE_SAVE_WINDOWJNFO_ 
AND_UNMAP, which saves information about all visible VAXTPU endows 
in the array window jirray and then unmaps all visible VAXTPU windows. 
The windows can be reconstructed later using the information in window_ 
array. 

The procedure uses the following variants of the built-in GETJNFO 
(window_variable): 

• GETJNFO (window_variable, "width") 

• GETJNFO (window_variable, "key_mapjist") 
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• GETJNFO (window_variable, ”scroll_bar", VERTICAL) 

• GETJNFO (window_variable, "scroll_bar_auto_thumb", VERTICAL) 

Warning. Digital does not guarantee that this example will work successfully 
with future versions. 

Example B-6 EVE Procedure That Unmaps Saved Windows 


PROCEDURE sample_save_window_info_and_unmap (; window_array) 

LOCAL the_count^ 
the_window, 
saved___buf fer, 
the_row, 
temp; 

ON__ERROR 

[TPU$__CONTROLC] : 

IF GET_INFO (saved_buffer, "type") = BUFFER 
THEN 

eve$message (EVE$_REBLDWINDOWS); 
eve$setup_windows (saved_buffer); 
eve$message (EVE$_WINDOWSREBLT); 

UPDATE (ALL); 

ENDIF; 

eve$learn_abort/ 

ABORT; 

[OTHERWISE]: 

ENDON_ERROR; 

the_count := 0; 

the_window := GET_INFO (WINDOWS, "first"); 

LOOP 

EXITIF the_window = 0; 

IF GET__INFO (the_window, "buffer") <> 0 
THEN 

the_count := the__count + 1; 

ENDIF; 

the_window := GET_INFO (WINDOWS, "next"); 

ENDLOOP; 

window_array := CREATE_ARRAY (the_count + 1, 0); 
window__array {0} := eve$x__nuinber_of_windows; 
the_window := eve$main_window; 

IF GET_INFO (the_window, "type") = WINDOW 
THEN 

saved__buffer := GET__INFO (the window, "buffer"); 

ENDIF; ■" 


(continued on next page) 


B-20 








Sample DECwindows VAXTPU Procedures 

B.7 Unmapping Saved Windows 


Example B-6 (Cent.) EVE Procedure That Unmaps Saved Windows 


LOOP 


EXITIF the_count = 0; 
the_window := CURRENT__WINDOW; 

EXITIF the_window =0; 
temp := CREATE_ARRAY (29); 
temp {1} := the_window; 

temp {2} := GET__INFO {the_window, "buffer"); 
temp {3} := GET_INFO (the__window, "top", WINDOW); 
temp {4} := GET__INFO (the_window, "length", WINDOW); 
temp {8} := get_info (the_window, "status_line") ; 

IF temp {8} <> 0 
THEN 

temp {5} := ON; 

ELSE 

temp {5} := OFF; 

ENDIF; 

POSITION (the_window); 

temp {6} := MARK (FREE_CURSOR); 

the___row := GET_INFO (the_window, "current_row") ; 

IF the_row = 0 
THEN 

the_row := temp {3}; 

ENDIF; 


temp 

{7} : 

= the_row + 

1 - temp {3} 

temp 

{9} : 

= GET_INFO I 

(the__window. 

temp 

{10} 

• = 

GET_ 

INFO 

(the_window. 

temp 

{11} 

: = 

GET 

’info 

(the_window. 

temp 

{12} 

: = 

GET_ 

’info 

(the__window. 

temp 

{13} 

: = 

GET_ 

’info 

(the_window. 

temp 

{14} 

: = 

GET 

‘info 

(the_window. 

temp 

{15} 

: = 

get" 

’info 

(the window. 

temp 

{16} 

: = 

get" 

’info 

(the_window. 

temp 

{17} 

; = 

get" 

’info 

(the window. 

temp 

{18} 

: = 

get" 

’info 

(the__window. 

temp 

{19} 

: = 

get’ 

INFO 

(the_window. 

temp 

{20} 

: = 

get” 

"info 

(the window. 

temp 

{21} 

; = 

get' 

"info 

(the_window. 

temp 

{22} 

: = 

get] 

"info 

(the window. 

IF GET INFO 

(the_ 

window, "pad") 


This statement uses 
GET_INFO (window, "width") 


"scroll__top") ; 
"scroll_bottom"); 
"scroll_amount"); 

"text"); 

"blink_video"); 
"blink_status"); 
"bold_video") ; 
"bold_status"); 
"reverse_video") ; 
"reverse_status"); 
"underline_video"); 
"underline_status"); 
"special_graphics_status"); 


THEN 

temp {23} ;= ON; 

ELSE 

temp {23} := OFF; 
ENDIF; 

temp {24} := GET_INFO 
temp {25} := GET_INFO 


(the_window, 
"shift_amount") ; 
(the_window, 

"key_map_list"); 


This statement uses 

GET_INFO (window, "key_map_list") 


(continued on next page) 
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Example B-6 (Cent.) EVE Procedure That Unmaps Saved Windows 


IF GET_INFO (SCREEN, "decwindows") 

THEN 

temp {26} := (GET__INFO (the__window, ! This statement uses 

"scroll_bar", ! GET__INFO (window, "scroll bar") . 
VERTICAL) <> 0); “ 

! If the vertical 
! scroll bar is 
! on, save the 
! information. 


IF temp {26} 
THEN 


temp {27} := GET_INFO (the_window, 

"scro1l_bar_auto_thumb", 
VERTICAL); 


ELSE 


This statement uses 
the GET_INFO 
("scroll_bar__auto_thumb) 
built-in. 


temp {27} := FALSE; 

ENDIF; 

temp {28} := (GET_INFO (the_window, "scroll bar", HORIZONTAL) <> 0)* 
IF temp {28} 

THEN 


temp {29} GET_INFO (the__window, "scroll_bar___auto thumb", 

HORIZONTAL); ~ 

ELSE 

temp {29} := FALSE; 

ENDIF; 

ELSE 

temp {26} := FALSE; 
temp {27} := FALSE; 
temp {28} ;= FALSE; 
temp {29} := FALSE; 

ENDIF; 

window_array {the__count} ;= temp; 

UNMAP (the_window); 
the_count := the_count - 1; 

ENDLOOP; 

eve$x_number__of_windows := 0; 

ENDPROCEDURE; 


B.8 Mapping Saved Windows 

Example B-7 shows the procedure SAMPLE_MAP_SAVED_WINDOWS, 
which maps windows whose descriptions have been saved previously. 
SAMPLE_MAP_SAVED_WINDOWS is passed the array window_array 
containing information about windows that have previously been saved 
and then unmapped. You can see an example of how such an array is 
created in Example B—6. The procedure maps the windows to buffers, 
giving the windows the same characteristics they had before they were 
xmmapped. 

The procedure includes the following built-ins: 

• SET (SCROLL_BAR) 
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• SET (SCROLL_BAR_AUTO_THUMB) 

• SET (WIDGET) 

• SET (WIDGET_CALLBACK) 

Warning: Digital does not guarantee that this example will work successfully 
with future versions. 

Example B-7 Procedure That Maps Saved Windows 


PROCEDURE sample_map_saved__windows (window_array) 

LOCAL temp, 

the__length, 
length__remaining, 
the_top, 
the_count, 
scroll_bar_widget, 
screen_length; 


ON__ERROR 

[TPU$__CONTROLC] : 

eve$message (EVE$__RESETUPWINDOWS) ; 
eve$setup_windows (window_array); 

UPDATE (ALL); 
eve$learn_abort; 

ABORT; 

[OTHERWISE]: 
endon_error; 

screen__length := eve$get___screen_height; 

eve $ $ u nmap_all_windows; 

eve$x nuinber_of__windows := window_array {0}; 
the__count := 1; 

LOOP 

EXITIF the_count > GET__INFO (window_array, "high_index”); 
temp := window_array {the_count}; 

eve$$map_window (temp {!}, temp {2}, temp {3}, temp {4}, temp {5}, 
~ temp {6}, temp {7}); 

IF temp {5} = ON 
THEN 

SET (STATUS_LINE, temp {!}, NONE, temp {8}); 

IF temp {15} 

THEN 

SET (STATUS_LINE, temp {1}, BLINK, temp {8}); 

ENDIF; 

IF temp {17} 

THEN 

SET (STATUS__LINE, temp {!}, BOLD, temp {8}); 

ENDIF; 

IF temp {19} 

THEN 

SET (STATUS__LINE, temp {!}, REVERSE, temp {8}); 

ENDIF; 

IF temp {21} 

THEN 

SET (STATUS_LINE, temp {!}, UNDERLINE, temp {8}); 

ENDIF; 


(continued on next page) 
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B.8 Mapping Saved Windows 


Example B-7 (Cent.) Procedure That Maps Saved Windows 


IF temp {22} 

THEN 

SET (STATUS_LINE, temp {!}, SPECIAL GRAPHICS, temp {8}); 
ENDIF; 

ENDIF; 

SET (WIDTH, temp {!}, temp {9}); 


SET (TEXT, temp 
IF temp {14} 
THEN 


temp 

{13}); 

SET 

ENDIF; 

(VIDEO, 

temp 

{1}, 

BLINK); 

IF temp 
THEN 

{16} 




SET 

ENDIF; 

(VIDEO, 

temp 

{1}, 

BOLD); 

IF temp 
THEN 

{18} 




SET 

ENDIF; 

(VIDEO, 

temp 

{1}, 

REVERSE); 

IF temp 
THEN 

{20} 




SET 

(VIDEO, 

temp 

{1}, 

UNDERLINE); 


ENDIF; 

SET (PAD, temp {!}, temp {23}); 

SHIFT (temp {!}, temp {24}); 
the_count := the_count + 1; 

ENDLOOP; 

IF GET__INFO (temp {25}, "type") = STRING 
THEN 

SET (KEY_MAP_LIST, temp {25}, temp {!}); 
ENDIF; 

IF GET_INFO (SCREEN, "deewindows") 

THEN 

IF temp {26} 

THEN 

scroll_bar_widget := SET (SCROLL_BAR, 

temp {!}, 
VERTICAL, ON); 


! This statement 
! uses the 
! SET (SCROLL_BAR) 
! built-in. 


SET (WIDGET__C ALLBACK, 

scroll_bar_widget, 
"eve$scroll_dispatch", 

'V'); 

SET (WIDGET, 

scroll__bar_widget, 
eve$$scroll__bar__callbacJcs) ; 


This statement uses the 
SET (WIDGET__CALLBACKS) 
built-in. 

! This statement uses 
! the SET (WIDGET) 

! built-in. 


eve$$scroll__bar__window (scroll_bar__widget) := temp {1}; 
IF temp {27} 


THEN 


SET 


ENDIF; 


(SCROLL_BAR__AUTO_THUMB, ! This statement uses the 
temp {1}, VERTICAL, ON); ! SET (SCROLL__BAR_AUTO_THUMB) 

! built-in. 


(continued on next page) 
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Example B-7 (Cent.) Procedure That Maps Saved Windows 


ENDIF; 

IF temp {28} 

THEN 

scroll_bar_widget := SET (SCROLL_BAR, temp {!}, HORIZONTAL, 

ON) ; 

SET (WIDGET__CALLBACK, scroll_bar_widget, "eve$scroll_dispatch”, 

'h'); 

SET (WIDGET, scroll__bar__widget, eve$$scroll___bar_callbac}cs) ; 
eve$$scroll_bar_window (scroll_bar__widget) := temp {!}; 

IF temp {29} 

THEN 

SET (SCROLL_BAR__AUTO_THUMB, temp {!}, HORIZONTAL, ON); 
ENDIF; 

ENDIF; 

ENDIF; 

UPDATE (ALL); 
the_count := 1; 

LOOP 

EXITIF the_count > GET_INFO (window_array, "high_index”); 
temp := window_array {the_count}; 

SET (SCROLLING, temp {!}, ON, temp {10}, temp {11}, temp {12}); 
the^count := the__count + 1; 

ENDLOOP; 

SET (PROMPT_AREA, screen__length - 1, 1, REVERSE); 

ENDPROCEDURE; 


B.9 Handling Callbacks from a Scroll Bar Widget 

Example B-8 shows one of the ways an application can use the statements 
POSITION (integer) and SET (WIDGET). The procedure is a portion of the 
EVE procedure eve$scroll_dispatch. You can find the original version in 
SYS$EXAMPLES:EVE$DECWINDOWS.TPU. For more information about 
nging the files in SYS$EXAMPLES as examples, see Section B.l. 

The procedure eve$scroll_dispatch is the callback routine handling 
callbacks from scroll bar widgets. The portion of the procedure shown 
here determines where to position the editing point based on how the user 
has changed the scroll bar slider. The procedure fetches the position of 
the slider with the built-in GETJNFO (widget_variable, "widget_info") 
and positions the editing point to the line in the buffer equivalent to 
the slider’s position in the scroll bar. Finally, the procedure updates the 
scroll bar’s resource values. For more information about the resource 
names used with the scroll bar widget, see the VMS DECwindows Toolkit 
Routines Reference Manual. 

EVE uses the following constants in this procedure: 

• EVE$DWT$C_NINC — A constant for the string "inc". This is the 
resource name for the amount that the scroll bar shder position is to 
be incremented or decremented when a scroll bar button is pressed. 
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• EVE$DWT$C_NPAGE_INC — A constant for the string "pageinc". 
This is the resource name for the amount that the scroll bar slider 
position is to be incremented or decremented when a click occurs 
within the scroll bar above or below the slider. 

• EVE$DWT$C_NMAX_VALUE — A constant for the string "maxYalue". 
This is the resource name for the maximum value of the scroll bar 
slider position. 

• EVE$DWT$C_NMIN_VALUE — A constant for the string "minValue". 
This is the resource name for the minimum value of the scroll bar 
slider position. 

• EVE$DWT$C_NVALUE — A constant for the string "value". This is 
the resource name for the top of the scroll bar slider position. 

• EVE$DWT$C_NSHOWN — A constant for the string "shown". This is 
the resource name for the size of the slider. 

• EVE$DWT$C_CRVALUE__CHANGE_CALLBACK — A constant for the 
callback reason code DWT$C^CR_VALUE_CHANGED. This reason 
code indicates that the user changed the value of the scroll bar shder. 

• EVE$K_CLOSURE — A constant for the string "closure", used as 
an index for the array returned by GETJNFO (WIDGET, "callback^ 
parameters", array). 

• EVE$K_REASON__CODE — A constant for the string "reason__code", 
used as an index for the array returned by GETJNFO (WIDGET, 
"callback_parameters", array). 

• EVE$K_WIDGET — A constant for the string "widget", used as an 
index for the array returned by GETJNFO (WIDGET, "callback_ 
parameters", array). 

Example B-8 EVE Procedure That Handles Callbacks from a Scroll Bar Widget 


PROCEDURE eve$scroll__dispatch 
LOCAL status, 

widget_called, 

widget_tag, 

widget__reason, 

scroll_bar_values, 

linenum, 

temp_array. 


ON__ERROR 

[TPU$_CONTROLC]: 

eve$learn_abort; 

ABORT; 

ENDON_ERROR 

©status := GET_INFO (WIDGET, "callback_paraineters", teinp_array) ; 


(continued on next page) 
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Example B-8 (Cent.) EVE Procedure That Handles Callbacks from a Scroll Bar Widget 


widget_called := temp__array {eve$k_widget}; 
widget_tag := temp_array {eve$k_closure}; 
widget__reason := temp_array {eve$k_reason_code}; 

POSITION (eve$$scroll___bar_window {widget__called}) ; 


scroll_bar_values := CREATE_ARRAY; 
scroll_bar_values {eve$dwt$c_ninc} := 0; 
scroll_bar_values {eve$dwt$c_npage_inc} := 0; 
scroll_bar_values {eve$dwt$c__nmax_value} := 0; 
scroll_bar_values {eve$dwt$c__nmin_value} := 0; 
scroll_bar_values {eve$dwt$c_nvalue} := 0; 
scroll_bar__values {eve$dwt$c_nshown} := 0; 

©status := GET_INFO (widget_called, ”widget__info”, scroll_bar_values) ; 

! The deleted statements scroll the window as dictated 
! by the callback reason. 


CASE widget_reason 


[ eve $ dwt $ c__crvalue_change_cal Iback ] : 

IF (scroll_bar__values {eve$dwt$c_nvalue} = 

scroll_bar_values {eve$dwt$c__nmin__value}) 

THEN 

POSITION (beginning_of (current__buf fer) ) ; 

ELSE 

© POSITION (scroll_bar_values {eve$dwt$c_nvalue}); 

ENDIF; 


scroll_bar_values {eve$dwt$c_ninc} := 1; 

scroll_bar_values {eve$dwt$c_npage_inc} := scroll__bar_values {eve$dwt$c_nshown} 

- 1 ; 

©SET (WIDGET, widget_called, scroll_bar_values) ; 


ENDPROCEDURE; 


O GETJNFO (WIDGET, "callback_parameters", array) returns an array 
containing the values for the current callback. The array elements 
are indexed by the strings "widget", "closure", and "reason^code" that 


B-27 









Sample DECwindows VAXTPU Procedures 

B.9 Handling Callbacks from a Scroll Bar Widget 


reference the widget that is calling back, the widget’s closure value, 
and the reason code for the callback. 

® GET_INFO (WIDGET, "widget_info", array) allows you to fetch 
information from a widget. The array parameter is indexed by 
the resource names associated with the specified widget. Note that 
resource names are case sensitive. Note, too, that the set of supported 
resources varies from one widget type to another. When you use GET_ 
INFO (widget, "widget_info", array), VAXTPU queries the widget for 
the requested information and puts the returned informaion in the 
array elements. Any previous values in the array are lost. 

® POSITION (integer) allows you to move the editing point to the record 
specified by the parameter integer. VAXTPU interprets this parameter 
as a record number. 

O SET (WIDGET, widget_variable, array) allows you to set resource 
values for the specified widget. The array parameter is indexed by 
the resource names associated with the specified widget. Note that 
resource names are case sensitive. Note, too, that the set of supported 
resources varies from one widget type to smother. 

B.10 Implementing the COPY SELECTION Operation 

Example B—9 shows one of the ways an application can use the READ_ 
GLOBAL_SELECT built-in. The procedure is a modified version of the 
EVE procedure EVE$STUFF_GLOBAL_SELECTION. You can find 
the original version in SYS$EXAMPLES:EVE$MOUSE.TPU. For more 
information about using the files in SYS$EXAMPLES as examples, see 
Section B.l. 

The procedure performs the following tasks: 

• Saves the location of the editing point and the buffer’s current mode. 

• Checks that DECwindows EVE is enabled and that EVE does not have 
input focus. 

• Obtains the location of the pointer cursor and positions the editing 
point at that location. 

• Sets the text mode to insert. 

• Reads the string-formatted contents of the primary global selection. 

(In this context, the parameter "STRING" means that the calling 
application is asking the application that owns the global selection for 
the string-formatted information in the specified global selection.) 

• Restores the editing point location and text mode to their previous 
values. 

EVE binds this procedure to the MBS key. Thus, using MBS, the user 
can direct EVE to copy selected material from a non-EVE DECwindows 
application to a DECwindows EVE buffer. In DECwindows documentation, 
this operation is called COPY SELECTION. 
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Example B-9 EVE Procedure That Implements the COPY SELECTION Operation 


PROCEDURE eve$stuff_global_selection 

LOCAL saved_position, 
saved__mode, 
this_buffer, 
the_window, 
the_column, 
the row; 


ON_ERROR 

[TPU$_CONTROLC]: 

IF saved_mode = OVERSTRIKE 
THEN 

SET (saved_mode, this_buffer); 

ENDIF; 

eve$$restore__position (saved__position) ; 
eve $1earn_abort; 

ABORT; 

[OTHERWISE]: 

IF saved_mode = OVERSTRIKE 
THEN 

SET (saved_mode, this___buf fer) ; 

ENDIF; 

eve$$restore_j50sition (saved_position); 
ENDON ERROR; 


this__buffer := current_buffer; 
saved__position ;= MARK (FREE__CURSOR) ; 
saved__mode := GET__INFO (this_buffer, "mode”); 

IF eve$x_decwindows__active 
THEN 

IF not GET__INFO (SCREEN, "input__focus") 

THEN 

IF LOCATE_MOUSE (the_window, ! This statement uses 

the_column, the_row) ! the LOCATE_MOUSE built-in. 

THEN 

IF the__row <> 0 

IF the_window <> eve$choice_window 
THEN 

POSITION (MOUSE); 

SET (INSERT, this_buffer); 

READ_GLOBAL__SELECT (PRIMARY, "STRING"); ! This statement 

! using READ_GLOBAL_SELECT 
! reads the string- 
! formatted contents 
! of the primary 
! global selection. 


(continued on next page) 
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Example B-9 (Cont.) EVE Procedure That Implements the COPY SELECTION Operation 


eve$$restore_position (saved__position) ; 
SET (saved_mode, this_buffer); 

UPDATE (CURRENT_WINDOW); 

RETURN (TRUE); 

ENDIF; 

ENDIF; 

ENDIF; 

ENDIF; 

ENDIF; 

RETURN (FALSE); 

ENDPROCEDURE; 


B.11 Reactivating a Select Range 

Example B-10 shows one of the ways an application can use the SET 
(GLOBAL_SELECT) built-in. The procedure is a modified version of the 
EVE procedure EVE$RESTORE_PRIMARY_SELECTION. You can find 
the original version in SYS$EXAMPLES:EVE$MOUSE.TPU. For more 
information about using the files in SYS$EXAMPLES as examples, see 
Section B.l. 

The procedure eve$restorejprimary_selection reactivates EVE’s select range 
when EVE regains input focus. 

Example B-10 EVE Procedure That Reactivates a Select Range 


PROCEDURE eve$restore_primary_selection 

LOCAL saved_position; 

ON_ERROR 

[TPU$_CONTROLC]: 

eve$$restore_position (saved_position); 
eve $ 1 e a r n__abo rt; 

ABORT; 

[OTHERWISE]: 

eve$$restoreposition (saved_position) ; 
ENDON_ERROR; 


IF NOT eve$x__decwindows_active 
THEN 

RETURN (FALSE); 

ENDIF; 

saved___position := MARK (FREE_CURSOR) ; 


(continued on next page) 
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Example B-10 (Cont.) EVE Procedure That Reactivates a Select Range 


IF GET_INFO (eve$$x_save_select_array, "type") = ARRAY 
THEN 

CASE eve$$x_save_select_array {"type"} 

[RANGE]: 

eve$select_a_range (eve$$x__save_select_array {"start"}, 
eve$$x_save_select_array {"end"}); 
eve$$x_state_array {eve$$k_select_all__active} := 

eve $ $ x_s ave__s e 1 e ct_a r r ay 
{"select_all"}; 

POSITION (eve$$x_save_select_array {"current"}); 
eve$start_j5ending_delete; 

[MARKER]: 

POSITION (eve$$x_save_select_array {"start"}); 
eve$x_select_position := select (eve$x_highlighting); 

POSITION (eve$$x_save_select_array {"end"}); 
eve$start_pending_delete; 

[OTHERWISE]: 

RETURN (FALSE); 

ENDCASE; 


eve$$restore_position (saved_position); 

eve$$found_post_filter; ! This is necessary if the 

! cursor is outside the selection. 

eve$$x_save_select_array {"type"} := 0; 

UPDATE (current_window); 

IF eve$x_decwindows_active 
THEN 

SET (GLOBAL_SELECT, SCREEN, PRIMARY); ! This statement using 

! SET (GLOBAL_SELECT) 

! requests ownership of 
! the primary global selection. 

ENDIF; 

RETURN (TRUE); 

ENDIF; 

RETURN (FALSE); 

ENDPROCEDURE; 


B.12 Copying Selected Material from EVE to Another DECwindows 
Application 

Example B-11 shows one of the ways a layered apphcation can use the 
WRITE_GLOBAL_SELECT built-in. The procedure is a modified version 
of the EVE procedure EVE$WRITE_GLOBAL_SELECT. You can find 
the original version in SYS$EXAMPLES:EVE$MOUSE.TPU. For more 
information about using the files in SYS$EXAMPLES as examples, see 
Section B.l. 

The procedure implements the operation of copying selected material from 
DECwindows EVE to another DECwindows application, in DECwindows 
documentation, this operation is called COPY SELECTION. 
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The procedure determines what property of the primary global selection 
is being requested, obtains the value of the appropriate property using a 
GETJNFO statement or an EVE procedure, and sends the information to 
the requesting application. 

Example B-11 EVE Procedure That Implements COPY SELECTION 


PROCEDURE eve$write_global_select ! EVE uses this procedure 

! to respond to requests 
! for information about 
! selections. 

LOCAL saved_position, 
the_data, 
temp_array, 
total_lines, 
the_line, 
status, 
eob_flag, 
percent; 


ON_ERROR 

[OTHERWISE]; 

eve$$restore_position (saved__position) ; 
ENDON_ERROR; 

saved_position := MARK (FREE__CURSOR) ; 

IF NOT eve$x_decwindows_active 
THEN 

RETURN (FALSE); 

ENDIF; 


the_data := 

temp_array := GET_INFO (SCREEN, "event”, GLOBAL_SELECT); 

! Finds out which global selection and which property 
! of the global selection are the subject of the 
! information request. 


CASE temp_array {2} ! Determines the property requested by the other application. 

["STRING", "TEXT"]: ! If one of these strings is requested, the 
! procedure sends the text in the global 
! selection to the requesting application. 

CASE temp_array {1} ! Checks which global selection was specified. 

[PRIMARY]; 

IF eve$x_select_position <> 0 
THEN 

POSITION (GET_INFO (eve$x_select__position, "buffer")); 


(continued on next page) 
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Example B-11 (Cent.) EVE Procedure That Implements COPY SELECTION 


IF GET_INFO (eve$x_select_position, "type") = RANGE 
THEN 

the_data := STR (eve$x_select_position); 

ELSE 

IF GET_INFO (eve$x___select_position, "type") = MARKER 
THEN 


the_data := STR (eve$select__a_range (eve$x__selectjposition, 

MARK (FREE_CURSOR))); 


ELSE 


the data := NONE; 


ENDIF; 

ENDIF; 

eve$$restore_position (saved_position); 
ENDIF; 

[OTHERWISE]: 

the data := NONE; 



ENDCASE; 


[OTHERWISE]; 

the data := NONE; 


The procedure does not send data if 


the requesting application has asked 


for something other than the text, 
the file name, or the line number. 


ENDCASE; 



WRITE GLOBAL SELECT (the data); 


! This statement sends the 
! requested information to 
! the requesting application. 


ENDPROCEDURE; 
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C.1 




This appendix lists the terminals that support screen-oriented editing 
and describes how differences among these termineds affect the way 
VAXTPU performs. This appendix also describes how VAXTPU can be 
run on terminals that do not support screen-oriented editing. Finally, this 
appendix tells you how VAXTPU manages wrapping and how you can 
modify that. 


Screen-Oriented Editing on Supported Terminais 

VAXTPU supports screen-oriented editing only on terminals that 
respond to ANSI control functions and that operate in ANSI mode. By 
default, your VAXTPU session runs with the screen management file 
TPU$CCTSHR.EXE. To check your terminal setting, enter the command 
SHOW TERMINAL at the DCL level. 

VAXTPU screen-oriented editing is designed to optimize the features 
available with the Digital VT300 and VT200 families of terminals and 
the Digital VTIOO family of terminals. VAXTPU does not support screen- 
oriented editing on Digital VT52-compatible terminals. Optimum VAXTPU 
performance is achieved on the VT300-series, VT200-series, and VTIOO- 
series terminals. Some of the high-performance characteristics of VAXTPU 
may not be apparent on the terminals listed in Table C-1 for the reasons 
stated. 


Table C-1 Terminal Behavior That Affects VAXTPU’s Performance 


Terminal 

Characteristic 

VT102 

Slow autorepeat rate 

VT240 

Slow autorepeat rate 

Slower scrolling region setup time than the VT220. 

GIGI 

One form of scrolling region (VAXTPU repaints screen, rather than use 
this scrolling mechanism) 

Variable autorepeat rate (cursor keys pick up speed when used 
repeatedly) 


C.1.1 Terminal Settings That Affect VAXTPU 

The following settings may affect the behavior of VAXTPU, depending on 
the terminal that you use. 
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132-Column Mode 

Only terminals that set the DEC_CRT mode bit and the advanced video 
mode bit can alter their physical width from 80 columns to 132 and back. 
All other terminals keep the physical width that is set when you enter the 
editor. 

For the VAXTPU screen manager to behave predictably on GIGI terminals, 
you should report the terminal width as 84 to VMS. Use the DCL 
command SET TERMINAL/DEVICE=VK100 to set the proper terminal 
width. 

Autorepeat ON/OFF and Auxiliary Keypad Enabling 

To take advantage of the built-in procedure SET (AUTO_REPEAT) or 
to enable the auxiliary keypad for applications mode, the terminal must 
be set to DEC_CRT3, DEC_CRT2, DEC_CRT, or VKIOO. Use the DCL 
command SET TERMINAL/DEVICE=characteristic to set the terminal. 

Control Sequence Introducer 

A feature of VAXTPU is that it can use one 8-bit control sequence 
introducer (CSI) to introduce a terminal control sequence. (Normally, 
the 2-character combination of the ESCAPE key and the left bracket ([) 
is used.) To take advantage of this feature, set your terminal to DEC_ 
CRT2 mode. The Digital VT300-series and VT220 and VT240 terminals 
currently support this feature. 

Cursor Positioning 

If your terminal sets the DEC_CRT mode bit, VAXTPU assumes that when 
control sequences that position the cursor to row 1 or column 1 are sent 
to the terminal, the 1 can be omitted. If your terminal does not behave 
correctly when it receives these control sequences, you must turn off the 
DEC_CRT mode bit. Some foreign terminals may not be fully compatible 
with VAXTPU and may exhibit this behavior. 

Edit Mode 

Terminals that are operating in edit mode allow the editor to take 
advantage of special edit-mode control sequences during deletion and 
insertion of text for optimization purposes. Some current Digital terminals 
that support edit mode include the W102, the VT220, the VT240, the 
VT241, and VT300-series terminals. 

8-Bit Characters 

ANSI terminals operating in 8-bit mode have the ability to use the 
supplemental characters and control sequences in the DEC Multinationad 
Character Set. The Digital VT300 series and the VT220 and VT240 
terminals currently support 8-bit character mode. If you have the 8- 
bit mode bit set, VAXTPU designates the DEC Multinational Character 
Set into G2 and invokes it into GR. For more information on how your 
terminal interacts with the DEC Multinational Character Set, refer to the 
programming manual for your specific terminal. 
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Scrolling 

Scrolling regions are only used for terminals that have the DEC_CRT 
mode bit set. On other terminals, VAXTPU repaints the window when 
a scroll would have been used (for example, when a line is deleted or 
inserted). 

Video Attributes 

When you set the video attributes of windows, markers, or ranges, only 
those attributes supported by your terminal tjrpe give predictable results. 
Most ANSI CRTs support reverse video. However, only terminals that 
support DEC_CRT mode with the advanced video option (AVO) have the 
full range of video attributes (reverse, bold, blink, underhne) that VAXTPU 
supports. 


C.1.2 The DCL Command SET TERMINAL 

When you use the DCL command SET TERMINAL to specify 
characteristics for your terminal, make sure to set only those 
characteristics that are supported by your terminal. If you set 
characteristics that the terminal does not support, the screen-oriented 
functions of VAXTPU may behave unpredictably. For example, if you run 
VAXTPU on a VTIOO terminal and you set the DEC_CRT2 characteristic 
that VTlOOs do not support, VAXTPU tries to use 8-bit CSI controls. 

This could cause “;7m” to appear on the screen where the reverse video 
attribute should be set. 

Most users do not knowingly set characteristics that are not supported 
by their terminals. However, if you temporarily move to a different type 
of terminal, your LOGIN.COM file may have characteristics set for your 
usual terminal that do not apply to the current terminal. This problem 
may also occur if, before running VAXTPU, you run a program that 
modifies your terminal characteristics without your knowledge. 

If you see unexpected video attributes or extraneous characters on the 
screen, exit from VAXTPU and check your terminal characteristics with 
the DCL command SHOW TERMINAL. 

Recover your files using the same terminal characteristics with which 
your files were created. Otherwise, a journal file inconsistency may occur, 
depending on how your interface is written. 


C.2 Line-Mode Editing on Unsupported Terminals 

If you want to run VAXTPU from an unsupported terminal, you must 
inform VAXTPU that you do not want to use screen capabilities. To invoke 
VAXTPU on an unsupported terminal, use the qualifier /NODISPLAY 
after the command EDIT/TPU. See Chapter 5 for more information on 
this qualifier. While in no-display mode, VAXTPU uses the RTL generic 
LIB$PUT_OUTPUT routine to display prompts and messages at the 
current location in SYS$OUTPUT. By using a combination of the built-in 
procedures READ__LINE and MESSAGE, you can devise your own line¬ 
mode editing functions or perform editing tasks from a batch job. See the 
sample line-mode editor in Appendix A. 
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C.3 Terminal Wrap 

If you have enabled an automatic wrap setting on your terminal, VAXTPU 
disables this setting in order to manage the screen more efficiently. When 
you exit from VAXTPU, VAXTPU restores all terminal characteristics 
to the setting of the DCL command SET TERMINAL before invoking 
VAXTPU. If the DCL command SET TERM/NOWRAP is active, VAXTPU 
leaves the hardware wrap off. However, if the DCL command SET TERM 
/WRAP is active, VAXTPU assumes that you want hardware wrap on, so it 
turns it on when you exit from VAXTPU. 

If you do not want this behavior of VAXTPU, you can prevent VAXTPU 
from turning on hardware wrap by specifying SET TERM/NOWRAP before 
invoking VAXTPU. You can enter the command interactively, or you can 
write a DCL command procedure that makes this setting part of your 
VAXTPU environment. Example C-1 shows a DCL command procedure 
that is used to control this terminal setting before and after a VAXTPU 
session. 

Example C-1 DCL Command Procedure for SET TERM/NOWRAP 


$ SET TERM/NOWRAP 

$ ASSIGN/USER SYS$COMMAND SYS$INPUT 
$ EDIT/TPU/SECTION = EDTSECINI 
$ SET TERM/WRAP 
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This appendix presents the messages produced by VAXTPU. The messages 
are listed alphabetically by their abbreviations in Table D-1. The text of 


the message and its severity level appears with each abbreviation. For 
an explanation of the severity levels for messages, see the VMS System 
Messages and Recovery Procedures Reference Manual. 

The VMS System Messages and Recovery Procedures Reference Manual 
also contains the VAXTPU messages, including the appropriate 
explanations of the messages and the suggested actions to recover from 
the errors which provoke the messages. 

Table D-1 VAXTPU Messages and Their Severity Levels 

Abbreviation 

Message 

Severity Level 

ACCVIO 

Access violation, reason mask= 'xx', virtual 
address=’xxxxxxxx’, PC=’xxxxxxxx’, PSL=’xxxxxxxx’ 

FATAL 

ADJSCROLLREG 

Scrolling parameters altered to top: ’top’, bottom: ’bottom’, 
amount: ’amount’ 

INFORMATIONAL 

AMBiGSYMUSED 

Ambiguous symbol ’name’ used as procedure parameter 

INFORMATIONAL 

ARGMiSMATCH 

Parameter ’number”s data type, ’type’, unsupported 

ERROR 

ASYNCACTIVE 

Journal file prohibited with asynchronous handlers declared 

WARNING 

ATLINE 

At line ’integer’ 

INFORMATIONAL 

ATPROCLINE 

At line ’Integer’ of procedure ’name’ 

INFORMATIONAL 

BADASSiGN 

Target of the assignment cannot be a function/keyword 

ERROR 

BADBUFWRITE 

Error occurred writing buffer ’buffer name’ 

WARNING 

BADCASELIMIT 

CASE constant outside CASE limits 

ERROR 

BADCASERANGE 

Invalid CASE range 

ERROR 

BADCHAR 

Unrecognized character in input 

ERROR 

BADDELETE 

Cannot modify constant integer, keyword, or string 

ERROR 

BADDiSPVAL 

display value = ’integer’, must be between ’integer’ and 
’integer’ 

WARNING 

BADEXITIF 

EXITIF occurs outside a LOOP 

ERROR 

BADFiRSTLINE 

First line = ’integer’, must be between ’integer’ and ’Integer’ 

WARNING 

BADJOUCHAR 

Expected character in journal file 

WARNING 

BADJOUCOM 

Journaled command file was ’string’, recovering with ’string’ 

ERROR 

BADJOUCPOS 

Journaled starting character was ’integer’, recovering with 
’Integer’ 

ERROR 

BADJOUEDIT 

Journaled edit mode was ’string’, recovering with ’string’ 

ERROR 
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Severity Level 

BADJOUEIGHT 

Journaled eightbit was ’string’, recovering with ’string’ 

ERROR 

BADJOUFILE 

Operation terminated due to error in journal file access 

ERROR 

BADJOUINIT 

Journaled init file was ’string’, recovering with ’string’ 

ERROR 

BADJOUINPUT 

Journaled input file was ’string’, recovering with ’string’ 

ERROR 

BADJOUKEY 

Expected key in journal file 

WARNING 

BADJOULINE 

Journaled line editing was ’string’, recovering with ’string’ 

ERROR 

BADJOULPOS 

Journaled starting line was ’integer’, recovering with 
’integer’ 

ERROR 

BADJOUPAGE 

Journaled page length was ’integer’, recovering with 
’integer’ 

ERROR 

BADJOUSEC 

Journaled section file was ’string’, recovering with ’string’ 

ERROR 

BADJOUSTR 

Expected string in journal file 

WARNING 

BADJOUTERM 

Journaled terminal type was ’string’, recovering with ’string’ 

ERROR 

BADJOUWIDTH 

Journaled width was ’integer’, recovering with ’integer’ 

ERROR 

BADKEY 

’keyword’ is an invalid keyword 

WARNING 

BADLENGTHCHANGE Terminal will not support change of length 

WARNING 

BADLOGIC 

Internal logic error detected 

FATAL 

BADMARGINS 

Margins specified incorrectly 

WARNING 

BADPROCNAME 

Variable used as a procedure 

ERROR 

BADPROMPTLEN 

Prompt area length = ’integer’, must be between ’integer’ 
and ’integer’ 

WARNING 

BADREAD 

Read next or read prev with current record of 0, dscb: 
’address’ 

FATAL 

BADREFCNT 

Ref count: ’ccc’, zap count: ’zzz’, address: ’xxxxxxxx’ 

FATAL 

BADREQUEST 

Request "’name”' of ’name’ is not understood 

WARNING 

BADSCREENWIDTH 

Terminal must be wider than widest window, ’integer’ 
columns 

WARNING 

BADSECTION 

Bad section file 

ERROR 

BADSTATUS 

Return status ’xxxxxxxx’ different from last signal ’xxxxxxxx’ 

FATAL 

BADSTRCNT 

Invalid string count found in journal file 

WARNING 

BADSYMTAB 

Bad symbol table 

ERROR 

BADUSERDESC 

Descriptor from user routine invalid or memory inaccessible 

ERROR 

BADVALUE 

Integer value ’integer’ is outside specified limits 

ERROR 

BADWIDTHCHANGE 

Terminal will not support change of width 

WARNING 

BADWINDADJUST 

Attempt to make window less than 1 line long, no 
adjustment 

WARNING 

BADWINDLEN 

Window length = ’integer’, must be between ’integer’ and 
’integer’ 

WARNING 
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Severity Level 

BEGOFBUF 

Attempt to move past the beginning of buffer ’buffer name’ 

WARNING 

BiNARYOPER 

Operand combination ’type’ ’oper’ ’type’ unsupported 

WARNING 

BOTLiNETRUNC 

Caiculated new last line ’integer’, changed to ’integer’ 

INFORMATIONAL 

BUiLTINiNV 

Builtin is invalid at this time 

ERROR 

CALLUSERFAIL 

CALL_USER routine failed with status %X’status’ 

WARNING 

CANCELQUiT 

QUIT canceled by request 

WARNING 

CANNOTUNSEL 

Cannot unselect item from unselect action routine 

ERROR 

CAPTIVE 

Unable to create a subprocess in a captive account 

WARNING 

CLIPBOARDFAIL 

Unexpected clipboard failure 

WARNING 

CLIPBOARDLOCKED 

Clipboard is locked by another process 

WARNING 

CLIPBOARDNODATA 

Clipboard does not contain the requested data 

WARNING 

CLIPBOARDZERO 

Clipboard data has 0 length 

WARNING 

CLOSEDIC 

Error closing the dictionary file 

ERROR 

CLOSEIN 

Error closing Input file ’file-spec’ 

ERROR 

CLOSEOUT 

Error closing output file ’file-spec’ 

ERROR 

CNVERR 

Error occurred in the conversion routine 

ERROR 

COMPILED 

Compilation completed without errors 

SUCCESS 

COMPILEFAIL 

Compilation aborted 

WARNING 

CONSTRTOOLARGE 

Constant string too large 

ERROR 

CONTRADEF 

Contradictory definition for variable or constant ’name’ 

ERROR 

CONTROLC 

Operation aborted by CTRL/C 

ERROR 

CREATED 

’file-spec’ created 

SUCCESS 

CREATEFAIL 

Unable to activate subprocess 

WARNING 

DDIFIN 

’count’ line(s), ’count’ frame(s) read from file ’name’ 

SUCCESS 

DDIFOUT 

’count’ line(s), ’count’ frame(s) written to file ’name’ 

SUCCESS 

DEBUG 

Breakpoint at line ’Integer’ 

SUCCESS 

DELETEFAjL 

Unable to terminate subprocess 

WARNING 

DICADD 

’word’ has been added to a dictionary as ’word’ 

SUCCESS 

DICDEL 

’word’ has been removed from ’word’ of a dictionary 

SUCCESS 

DICUPDERR 

Error updating dictionary file 

ERROR 

DIVBYZERO 

Divide by zero 

ERROR 

DUPBUFNAME 

Buffer ’name’ already exists 

WARNING 

DUPKEYMAPLIST 

Attempt to define a duplicate key-map list ’key-map-list- 
name’ 

WARNING 

DUPKEYMAP 

Attempt to define a duplicate key map ’key-map-name’ 

WARNING 

EMPTYKMLIST 

Key-map list ’key-map-list-name’ does not contain any key 
maps 

WARNING 
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ENDOFBUF 

Attempt to move past the end of buffer ’buffer name’ 

WARNING 

ENDOFLINE 

Returning a range of text with an end of line 

SUCCESS 

ERRSYMACTIVE 

Special error symbol already active 

WARNING 

EXECUTEFAIL 

Execution aborted 

WARNING 

EXITFAIL 

Attempt to EXIT was unsuccessful 

WARNING 

EXITING 

Editor exiting 

SUCCESS 

EXPCLA 

The current clause has been expanded 

INFORMATIONAL 

EXPCOMPLEX 

Expression too complex 

ERROR 

EXPECTED 

One of the following symbols was expected: 

INFORMATIONAL 

EXTNOTFOUND 

Extension ’name’ not found 

ERROR 

EXTRANEOUSARGS 

One or more extraneous arguments specified 

ERROR 

FACTOOLONG 

Facility name, ’name’, exceeds maximum length ’integer’ 

WARNING 

FAILURE 

Internal VAXTPU failure detected at PC ’number’ 

FATAL 

FAILURE_STATUS 

Facility ’name’ returned failure status of ’xxxxxxxx’ 

ERROR 

FENCEPOST 

No visible record found in specified range 

WARNING 

FILECONVERTED 

File format is being converted to a supported type 

ERROR 

FILEIN 

’count’ line(s) read from file ’name’ 

SUCCESS 

FILEOUT 

’count’ llne(s) written to file ’name’ 

SUCCESS 

FLAGTRUNC 

Value of message flags exceeds maximum value 15, 
truncated 

WARNING 

FREEMEM 

Memory deallocation failure 

FATAL 

FROMBUILTIN 

Called from builtin ’name’ 

INFORMATIONAL 

FROMLINE 

Called from line ’integer’ 

INFORMATIONAL 

FROMPROCLINE 

Called from line ’integer' of procedure ’name’ 

INFORMATIONAL 

GBLSELOWNER 

You are the global selection owner 

WARNING 

GETMEM 

Memory allocation failure (Insufficient virtual memory) 

ERROR 

HIDDEN 

Global variable ’name’ by declaration 

INFORMATIONAL 

IDMISMATCH 

Section NOT restored, section file must be rebuilt 

FATAL 

ILLCONDIT 

Illegal compilation conditional 

ERROR 

ILLEGALTYPE 

Illegal data type 

ERROR 

ILLPATAS 

Pattern assignment target only valid in procedure ’name’ 

ERROR 

ILLREQUEST 

Request "’name”' is invalid 

WARNING 

ILLSEVERITY 

Illegal severity of ’value’ specified, error severity used 

WARNING 

INBUILTIN 

Occurred in builtin ’name’ 

INFORMATIONAL 

INCKWDCOM 

Inconsistent keyword combination 

WARNING 

INDEXTYPE 

Array Index data type, ’type’, unsupported 

WARNING 
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INPUT_CANCELED 

Input request canceled 

WARNING 

INSVIRMEM 

Insufficient virtual memory 

FATAL 

INVACCESS 

Invalid file access specified 

FATAL 

INVBUFDELETE 

Cannot delete a permanent buffer 

WARNING 

INVDEVTYPE 

Invalid device type 

FATAL 

INVFAOPARAM 

FAO parameter ’integer’ must be string or integer 

WARNING 

INVGBLSELDATA 

The selected data cannot be processed 

WARNING 

INVIOCODE 

Invalid Operation Code passed to an I/O operation 

ERROR 

INVITEMCODE 

Invalid item code specified in list 

FATAL 

INVNUMSTR 

Invalid numeric string 

WARNING 

INVPARAM 

Parameter ’number”s data type, ’type’, illegal; expected 
’type’ 

ERROR 

INVRANGE 

Invalid range enclosure specified 

WARNING 

INVTABSPEC 

Tabs specification incorrect, not changed 

WARNING 

INVTIME 

Invalid time interval 

WARNING 

JNLACTIVE 

Asynchronous actions prohibited when journal file open 

WARNING 

JNLNOTOPEN 

Journal file not open, recovery aborted 

ERROR 

JNLOPEN 

Journal file already open 

ERROR 

JOURNALBEG 

Journal of edit session started 

INFORMATIONAL 

JOURNALCLOSE 

Journal file successfully closed, journaling stopped 

SUCCESS 

JOURNALEOF 

End of journal file found unexpectedly 

WARNING 

JRNLBUFBEG 

Journaling started for buffer ’buffer name’ 

INFORMATIONAL 

JRNLNOTSAFE 

Buffer ’buffer name’ is not safe for journaling 

WARNING 

JRNLOPEN 

Journal file already open for buffer ’buffer name’ 

WARNING 

KEYMAPNOTFND 

Key map ’key-map-name’ not found in key-map list ’key- 
map-list-name’ 

WARNING 

KEYSUPERSEDED 

Definition of key ’name’ superseded 

INFORMATIONAL 

KEYWORDPARAM 

Keyword ’name’ used as procedure/variable/constant 

ERROR 

LINENOTMOD 

Attempt to change unmodifiable line(s) 

WARNING 

LINETOOLONG 

Line is maximum length, cannot add text to it 

WARNING 

MAXMAPPEDBUF 

A single buffer can be mapped to at most ’count’ window(s) 

WARNING 

MAXVALUE 

Maximum value is ’integer’ 

WARNING 

MINVALUE 

Minimum value Is ’integer’ 

WARNING 

MISSINGQUOTE 

Missing quote 

ERROR 

MISSYMTAB 

Missing symbol table 

ERROR 

MIXEDTYPES 

Operator with mixed or unsupported data types 

ERROR 

MODRANGEMARKS 

MODIFY_RANGE requires either two marks or none 

ERROR 
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MOUSEINV 

Mouse location information is invalid 

WARNING 

MOVETOCOPYTEXT 

Moving unmodifiable line(s) from buffer ’string’ changed to 
copy 

WARNING 

MOVETOCOPY 

Move from unmodifiable buffer ’string’ changed to copy 

WARNING 

MSGBUFSET 

Attempt to change modifiable setting of message buffer 

WARNING 

MSGNOTFND 

Message was not found; the default message has been 
returned 

WARNING 

MULTIDEF 

Parameter/local/constant ’name’ multiply defined 

ERROR 

MULTIPLENAMES 

There is more than one name matching, all are returned 

WARNING 

MULTISELECT 

Multiple identical CASE selectors 

ERROR 

MUSTBECONST 

Expression must be a compile-time constant 

ERROR 

MUSTBEONE 

String must be 1 character long 

WARNING 

NEEDFILENAME 

Type filename for buffer ’name’ (press RETURN to not 
write it): 

SUCCESS 

NEEDTOASSIGN 

Built-in must return a value 

ERROR 

NOASSIGNMENT 

Expression without assignment 

ERROR 

NOBREAKPOiNT 

No breakpoint is active 

WARNING 

NOCACHE 

Insufficient virtual memory to allocate a new cache 

ERROR 

NOCALLUSER 

Could not find a routine for CALL__USER to invoke 

ERROR 

NOCHARREAD 

No character was read by the READ__CHAR builtin 

WARNING 

NOCLA 

No conversion source has been specified yet 

WARNING 

NOCOPYBUF 

Cannot COPY a buffer to itself 

WARNING 

NOCURRENTBUF 

No buffer has been selected as default 

WARNING 

NODEFINITION 

Key ’keyname’ currently has no definition 

WARNING 

NODICENT 

No entry found in a dictionary 

WARNING 

NODICUPD 

The dictionary is restricted updating 

WARNING 

NODIC 

No dictionary available in this editing session 

WARNING 

NOENDOFLINE 

Returning a range of text with no end of line 

SUCCESS 

NOEOBSTR 

Cannot return a string at end of buffer 

WARNING 

NOFILEACCESS 

Unable to access file ’name’ 

ERROR 

NOFILEROUTINE 

No routine specified to perform FILE I/O 

FATAL 

NOFOCUSOWNER 

There is no input focus owner 

WARNING 

NOGBLSELDATA 

No global selection data 

WARNING 

NOGBLSELOWNER 

There Is no global selection owner 

WARNING 

NOJOURNAL 

Editing session Is not being journaled 

WARNING 

NOKEYMAPLIST 

Attempt to access an undefined key-map list ’key-map-list- 
name’ 

WARNING 
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NOKEYMAP 

Attempt to access an undefined key map ’key-map-name’ 

WARNING 

NONAMES 

There are no names matching the one requested 

WARNING 

NONANSICRT 

SYS$INPUT must be supported CRT 

ERROR 

NOPARENT 

There is no parent process to attach to 

WARNING 

NOPROCESS 

No subprocess to interact with 

WARNING 

NOREDEFINE 

Built-in procedure ’name’ cannot be redefined 

ERROR 

NORETURNVALUE 

Built-in does not return a value 

ERROR 

NOSELECT 

No select active 

WARNING 

NOSHOWBUF 

Variable SHOW_BUFFER does not exist or is not a buffer 

WARNING 

NOTARRAY 

Indexed variable is not an array 

WARNING 

NOTDEFINABLE 

That key is not definable 

WARNING 

NOTERRORKEYWORD Error handler selector is not an error keyword 

ERROR 

NOTIMPLEMENTED 

Builtin compiled by ’name’ is not implemented by ’name’ 

ERROR 

NOTJOURNAL 

’file’ is not a journal file 

ERROR 

NOTLEARNING 

You have not begun a learn sequence 

WARNING 

NOTMODIFIABLE 

Attempt to change unmodifiable buffer ’string’ 

WARNING 

NOTSAMEBUF 

The markers are not in the same buffer 

WARNING 

NOTSUBCLASS 

Object is not a subclass of WindowObjClass 

WARNING 

NOTYET 

Not yet implemented 

WARNING 

NOWINDOW 

Attempt to position the cursor outside all of the mapped 
windows 

WARNING 

NO 

NO 

INFORMATIONAL 

NULLSTRING 

Null string used 

WARNING 

OCCLUDED 

Builtin/keyword ’name’ occluded by declaration 

INFORMATIONAL 

ONDELRECLIST 

Attempt to access a record on the deleted list 

FATAL 

ONELEARN 

Cannot start a learn sequence while one is active 

WARNING 

ONESELECT 

Select already active, maximum 1 per buffer 

WARNING 

OPENDIC 

Error opening the dictionary file 

ERROR 

OPENIN 

Error opening ’Input-file’ as input 

ERROR 

OPENOUT 

Error opening ’output-file’ as output 

ERROR 

OVERLAPRANGE 

Overlapping ranges, operation terminated 

WARNING 

PARSEFAIL 

Error parsing ’file-spec’ 

WARNING 

PARSEOVER 

Parser stack overflow 

ERROR 

PREMATUREEOF 

Premature end-of-file detected 

ERROR 

PRESSRET 

Press RETURN to continue... 

SUCCESS 

PROCESSBEG 

Subprocess activated 

SUCCESS 
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PROCESSEND 

Subprocess terminated 

SUCCESS 

PROCSUPERSEDED 

Definition of procedure ’name’ superseded 

INFORMATIONAL 

QUITTING 

Editor quitting 

SUCCESS 

READABORTED 

READ_CHAR, READ_KEY, or READ_LINE builtin was 
aborted 

WARNING 

READERR 

Error reading ’input-file-spec’ 

ERROR 

READQUEHEADER 

Attempt to read queue header of dscb: ’address’ 

FATAL 

READZERO 

Read of record id 0, dscb: ’address’ 

FATAL 

REALLYQUIT 

Buffer modifications will not be saved, continue quitting (Y 
or N)? 

SUCCESS 

REALLYRECOVER 

Continue recovering (Y or N)? 

SUCCESS 

RECJNLOPEN 

Journal file open, recovery status unchanged 

ERROR 

RECOVERABORT 

Recovery aborted by journal file inconsistency, journal file 
closed 

WARNING 

RECOVERBEG 

Recovery started 

SUCCESS 

RECOVERBUFBEG 

Recovery started for buffer ’buffer name’ 

SUCCESS 

RECOVERBUFEND 

Recovery complete for buffer ’buffer name’ 

SUCCESS 

RECOVERBUFFILE1 

Can not recover from file ’file name’ 

SUCCESS 

RECOVERBUFFILE2 

Please type in a new file specification: 

SUCCESS 

RECOVEREND 

Recovery complete 

SUCCESS 

RECOVERFAIL 

Recovery terminated abnormally, journal file inconsistency 

ERROR 

RECOVERQUIT 

No file name specified, nothing recovered 

WARNING 

RECURLEARN 

Learn sequence replay halted due to recursion 

WARNING 

RECURREAD 

READ_LINE cannot be part of user defined READ__LINE 
procedure 

WARNING 

REFRESH_NEEDED 

Screen refresh needed 

WARNING 

REGWIDDUP 

Registration string already associated with a different 
widget 

WARNING 

REPLAYFAIL 

An inconsistency has been discovered, halting execution 

WARNING 

REPLAYWARNING 

An inconsistency has been discovered, continuing 
execution 

WARNING 

REQARGSMISSING 

One or more required arguments missing 

ERROR 

REQUIRESDECW 

Feature requires the VAXTPU DECwindows screen updater 

ERROR 

REQUIRESTERM 

Feature requires a terminal 

ERROR 

RESTOREFAIL 

Error during RESTORE operation 

ERROR 

REVERSECASE 

CASE limits were reversed 

INFORMATIONAL 

ROUND 

FORWARD was rounded to the top 

INFORMATIONAL 

SAVEAMBIGSYM 

Saving ambiguous symbol ’name’ 

INFORMATIONAL 
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SAVEERROR 

Error during SAVE operation 

ERROR 

SAVEUNDEFPROC 

Saving undefined procedure ’name’ 

INFORMATIONAL 

SCANADVANCE 

*** Scanner advanced to "’name’" *** 

ERROR 

SEARCHFAIL 

Error searching for ’file-spec’ 

WARNING 

SECTRESTORED 

’count’ procedure(s), ’count’ variable(s), ’count’ key(s) 
restored 

INFORMATIONAL 

SECTSAVED 

’count’ procedure(s), ’count’ variable(s), ’count’ key(s) 
saved 

SUCCESS 

SECTUNDEFPROC 

Saved ’count’ undefined piocedure(s), ’count’ ambiguous 
symboi(s) 

WARNING 

SELRANGEZERO 

Select range has 0 length 

WARNING 

SENDFAIL 

Unable to send to subprocess 

WARNING 

SHRCLA 

The current clause has been shrunk 

INFORMATIONAL 

SOURCELINE 

At source iine ’integer’ 

INFORMATIONAL 

STACKOVER 

Stack overflow during compilation 

ERROR 

STATOOLONG 

Truncating status line to ’count’ characters 

INFORMATIONAL 

STRNOTFOUND 

String not found 

WARNING 

STRTOOLARGE 

String greater than 65535 characters 

ERROR 

STRTOOLNG 

String is too long for a conversion source 

ERROR 

SUCCESS 

Successful completion 

SUCCESS 

SYMDELETE 

*** Error symbol deleted *** 

ERROR 

SYMINSERT 

*** "’name"' inserted before error symbol *** 

ERROR 

SYMREPLACE 

*** Error symbol replaced by "’name"' *** 

ERROR 

SYMTBLFUL 

All symbol tables are full 

ERROR 

SYNTAXERROR 

Syntax error 

ERROR 

SYSERROR 

System service error 

ERROR 

TEXT 

’message’ 

INFORMATIONAL 

TIMEOUT 

Builtin timed out 

WARNING 

TOOFEW 

Too few arguments 

ERROR 

TOOMANYCLA 

Too many clauses are found while converting 

WARNING 

TOOMANYPARAM 

Too many formal parameters/local variables 

ERROR 

TOOMANYRECS 

Too many records 

ERROR 

TOOMANY 

Too many arguments 

ERROR 

TOPLINETRUNC 

Calculated new first line ’integer’, changed to 1 

INFORMATIONAL 

TRUNCATE 

Line truncated to ’count’ characters 

WARNING 

UKNFACILITY 

Unknown facility code specified 

WARNING 

UNARYOPER 

Operand combination ’oper’ ’type’ unsupported 

WARNING 
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UNDEFINEDPROC 

Undefined procedure call ’name’ 

ERROR 

UNDWIDCLA 

Undefined widget class specified 

WARNING 

UNKESCAPE 

Unknown escape sequence read 

WARNING 

UNKKEYWORD 

An unknown keyword has been used as an argument 

ERROR 

UNKLEXICAL 

Unknown lexical element 

ERROR 

UNKOPCODE 

Unknown opcode ’value’ 

ERROR 

UNKTYPE 

Unknown data type ’value’ 

ERROR 

UNKWNDESC 

Unknown descriptor type 

ERROR 

UNREACHABLE 

Unreachable code 

INFORMATIONAL 

WIDMISMATCH 

Parameter ’number”s class, ’class’, unsupported 

ERROR 

WINDNOTMAPPED 

The window is not mapped to a buffer 

WARNING 

WINDNOTVIS 

Built-in cannot operate on an invisible window 

WARNING 

WRITEERR 

Error writing ’output-file-spec’ 

ERROR 

YES 

YES 

INFORMATIONAL 
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DEC Multinational Character Set 


This appendix presents the DEC multinational character set. In Table E-1 
the control characters are shown as reverse question marks, which is how 
they appear on the VT300 series and VT200 series of terminals. On the 
VTIOO series of terminals, control characters appear as rectangles. 


Table E-1 DEC Multinational Character Set 


Graphic 

Decimal 

Value 

Abbreviation 

Description 

? 

0 

NUL 

null character 

? 

1 

SOH 

start of heading 

9 

2 

STX 

start of text 

? 

3 

ETX 

end of text 

? 

4 

EOT 

end of transmission 

? 

5 

ENQ 

enquiry 

? 

6 

ACK 

acknowledge 

? 

7 

BEL 

bell 

? 

8 

BS 

backspace 


9 

HT 

horizontal tabulation 

ip 

10 

LF 

line feed 


11 

VT 

vertical tabulation 


12 

FF 

form feed 

% 

13 

CR 

carriage return 

? 

14 

SO 

shift out 

? 

15 

SI 

shift in 

? 

16 

DLE 

data link escape 

? 

17 

DC1 

device control 1 

? 

18 

DC2 

device control 2 

? 

19 

DC3 

device control 3 

? 

20 

DC4 

device control 4 

? 

21 

NAK 

negative acknowledge 

? 

22 

SYN 

synchronous idle 

? 

23 

ETB 

end of transmission block 

? 

24 

CAN 

cancel 

? 

25 

EM 

end of medium 

? 

26 

SUB 

substitute 
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Value 
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? 

27 

ESC 

escape 

? 

28 

FS 

file separator 

? 

29 

GS 

group separator 

? 

30 

RS 

record separator 

? 

31 

US 

unit separator 

? 

32 

SP 

space 

! 

33 

! 

exclamation point 

II 

34 

II 

quotation marks (double quote) 

# 

35 

# 

number sign 

$ 

36 

$ 

dollar sign 

% 

37 

% 

percent sign 

& 

38 

& 

ampersand 

r 

39 

t 

apostrophe (single quote) 

( 

40 

( 

opening parenthesis 

) 

41 

) 

closing parenthesis 

* 

42 

* 

asterisk 

+ 

43 

+ 

plus 

» 

44 

1 

comma 

- 

45 

- 

hyphen or minus 

. 

46 


period or decimal point 

/ 

47 

/ 

slash 

0 

48 

0 

zero 

1 

49 

1 

one 

2 

50 

2 

two 

3 

51 

3 

three 

4 

52 

4 

four 

5 

53 

5 

five 

6 

54 

6 

six 

7 

55 

7 

seven 

8 

56 

8 

eight 

9 

57 

9 

nine 

: 

58 

: 

colon 

1 

59 

1 

semicolon 

< 

60 

< 

less than 

= 

61 

= 

equals 
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Description 

> 

62 

> 

greater than 

? 

63 

? 

question mark 

@ 

64 

@ 

commercial at 

A 

65 

A 

uppercase A 

B 

66 

B 

uppercase B 

c 

67 

C 

uppercase C 

D 

68 

D 

uppercase D 

E 

69 

E 

uppercase E 

F 

70 

F 

uppercase F 

G 

71 

G 

uppercase G 

H 

72 

H 

uppercase H 

1 

73 

1 

uppercase I 

j 

74 

J 

uppercase J 

K 

75 

K 

uppercase K 

L 

76 

L 

uppercase L 

M 

77 

M 

uppercase M 

N 

78 

N 

uppercase N 

O 

79 

0 

uppercase 0 

P 

80 

P 

uppercase P 

Q 

81 

Q 

uppercase Q 

R 

82 

R 

uppercase R 

S 

83 

S 

uppercase S 

T 

84 

T 

uppercase T 

U 

85 

U 

uppercase U 

V 

86 

V 

uppercase V 

w 

87 

w 

uppercase W 

X 

88 

X 

uppercase X 

Y 

89 

Y 

uppercase Y 

z 

90 

z 

uppercase Z 

[ 

91 

[ 

opening bracket 

\ 

92 

\ 

back slash 

] 

93 

] 

closing bracket 

A 

94 

A 

circumflex 

_ 

95 

_ 

underline (underscore) 

< 

96 

i 

grave accent 


(continued on next page) 
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Table E-1 (Cont.) DEC Multinational Character Set 


Graphic 

Decimal 

Value 

Abbreviation 

Description 

a 

97 

a 

lowercase a 

b 

98 

b 

lowercase b 

c 

99 

c 

lowercase c 

d 

100 

d 

lowercase d 

e 

101 

e 

lowercase e 

f 

102 

f 

lowercase f 

g 

103 

g 

lowercase g 

h 

104 

h 

lowercase h 

i 

105 

i 

lowercase i 

j 

106 

j 

lowercase j 

k 

107 

k 

lowercase k 

1 

108 

1 

lowercase 1 

m 

109 

m 

lowercase m 

n 

110 

n 

lowercase n 

0 

111 

0 

lowercase o 

P 

112 

P 

lowercase p 

q 

113 

q 

lowercase q 

r 

114 

r 

lowercase r 

s 

115 

s 

lowercase s 

t 

116 

t 

lowercase t 

u 

117 

u 

lowercase u 

V 

118 

V 

lowercase v 

w 

119 

w 

lowercase w 

X 

120 

X 

lowercase x 

y 

121 

y 

lowercase y 

2 

122 

z 

lowercase z 

{ 

123 

{ 

opening brace 

1 

124 

1 

vertical line 

} 

125 

} 

closing brace 

- 

126 

- 

tilde 

DEL 

127 

DEL 

delete, rubout 

? 

128 

— 

[reserved] 

? 

129 

— 

[reserved] 

? 

130 

— 

[reserved] 

? 

131 

— 

[reserved] 


(continued on next page) 
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DEC Multinational Character Set 


Table E-1 (Cent.) DEC Multinational Character Set 


Graphic 

Decimal 

Value 

Abbreviation 

Description 

? 

132 

IND 

index 

? 

133 

NEL 

next line 

? 

134 

SSA 

start of selected area 

? 

135 

ESA 

end of selected area 

? 

136 

HTS 

horizontal tab set 

? 

137 

HTJ 

horizontal tab set with justification 

? 

138 

VTS 

vertical tab set 

? 

139 

PLD 

partial line down 

? 

140 

PLU 

partial line up 

? 

141 

Rl 

reverse index 

? 

142 

SS2 

single shift 2 

? 

143 

SS3 

single shift 3 

? 

144 

DCS 

device control string 

? 

145 

PU1 

private use 1 

? 

146 

PU2 

private use 2 

? 

147 

STS 

set transmit state 

? 

148 

CCH 

cancel character 

? 

149 

MW 

message waiting 

? 

150 

SPA 

start of protected area 

? 

151 

EPA 

end of protected area 

? 

152 

— 

[reserved] 

? 

153 

— 

[reserved] 

? 

154 

— 

[reserved] 

? 

155 

CSI 

control sequence introducer 

? 

156 

ST 

string terminator 

? 

157 

OSC 

operating system command 

? 

158 

PM 

privacy message 

? 

159 

APC 

application program command 

? 

160 

— 

[reserved] 

i 

161 

i 

inverted exclamation mark 

0 

162 

0 

cent sign 

£ 

163 

£ 

pound sign 

? 

164 

— 

[reserved] 

¥ 

165 

¥ 

yen sign 

? 

166 

— 

[reserved] 


(continued on next page) 
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Table E-1 (Cent.) DEC Multinational Character Set 


Decimal 

Graphic Value 

Abbreviation Description 

§ 

167 

§ 

section sign 

D 

168 

n 

general currency sign 

© 

169 

© 

copyright sign 

a 

170 

a 

feminine ordinal indicator 

« 

171 

« 

angle quotation mark left 

? 

172 

— 

[reserved] 

? 

173 

— 

[reserved] 

? 

174 

— 

[reserved] 

? 

175 

— 

[reserved] 

o 

176 

O 

degree sign 

± 

177 

± 

plus/minus sign 

2 

178 

2 

superscript 2 

3 

179 

3 

superscript 3 

? 

180 

— 

[reserved] 

M 

181 

M 

micro sign 

H 

182 

H 

paragraph sign, piicrow 


183 

• 

middle dot 

? 

184 

— 

[reserved] 

1 

185 

1 

superscript 1 

Q 

186 

Q 

masculine ordinal indicator 

» 

187 

» 

angle quotation mark right 

Va 

188 

Va 

fraction one quarter 

Vz 

189 

Vz 

fraction one half 

? 

190 

— 

[reserved] 

6 

191 

6 

inverted question mark 

A 

192 

A 

uppercase A with grave accent 

A 

193 

A 

uppercase A with acute accent 

A 

194 

A 

uppercase A with circumflex 

A 

195 

A 

uppercase A with tilde 

A 

196 

A 

uppercase A with umlaut, (diaeresis) 

A 

197 

A 

uppercase A with ring 

/E 

198 

/E 

uppercase AE diphthong 

Q 

199 

Q 

uppercase C with cedilla 

E 

200 


uppercase E with grave accent 

E 

201 

E 

uppercase E with acute accent 


(continued on next page) 
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Table E-1 (Cont.) DEC Multinational Character Set 


Graphic 

Decimal 

Value 

Abbreviation 

Description 

E 

202 

E 

uppercase E with circumflex 

E 

203 

E 

uppercase E with umlaut, (diaeresis) 

1 

204 

1 

uppercase 1 with grave accent 

1 

205 

i 

uppercase 1 with acute accent 

1 

206 

1 

uppercase 1 with circumflex 

■( 

207 

■( 

uppercase 1 with umlaut, (diaeresis) 

? 

208 

— 

[reserved] 

N 

209 

1^ 

uppercase N with tilde 

6 

210 

6 

uppercase 0 with grave accent 

6 

211 

C 

uppercase 0 with acute accent 

6 

212 

6 

uppercase 0 with circumflex 

0 

213 

0 

uppercase 0 with tilde 

0 

214 

6 

uppercase 0 with umlaut, (diaeresis) 

CE 

215 

CE 

uppercase OE ligature 

0 

216 

0 

uppercase 0 with slash 

0 

217 

0 

uppercase U with grave accent 

Cl 

218 

0 

uppercase U with acute accent 

0 

219 

0 

uppercase U with circumflex 

0 

220 

u 

uppercase U with umlaut, (diaeresis) 

9 

221 

Y 

uppercase Y with umlaut, (diaeresis) 

? 

222 

— 

[reserved] 

B 

223 

B 

German lowercase sharp s 

k 

224 

k 

lowercase a with grave accent 

k 

225 

k 

lowercase a with acute accent 

a 

226 

a 

lowercase a with circumflex 

a 

227 

a 

lowercase a with tilde 

k 

228 

a 

lowercase a with umlaut, (diaeresis) 

k 

229 

k 

lowercase a with ring 

ee 

230 

ae 

lowercase ae diphthong 

9 

231 

9 

lowercase c with cedilla 

k 

232 

k 

lowercase e with grave accent 

6 

233 

k 

lowercase e with acute accent 

e 

234 

e 

lowercase e with circumflex 

e 

235 

e 

lowercase e with umlaut, (diaeresis) 

1 

236 

1 

lowercase i with grave accent 


(continued on next page) 
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Table E-1 (Cent.) DEC Multinational Character Set 


Graphic 

Decimal 

Value 

Abbreviation 

Description 

f 

237 

1 

lowercase i with acute accent 

1 

238 

1 

lowercase i with circumflex 

Y 

239 

T 

lowercase i with umlaut, (diaeresis) 

? 

240 

— 

[reserved] 

n 

241 

n 

lowercase n with tilde 

6 

242 

6 

lowercase o with grave accent 

6 

243 

6 

lowercase o with acute accent 

6 

244 

0 

lowercase o with circumflex 

6 

245 

5 

lowercase o with tilde 

6 

246 

6 

lowercase o with umlaut, (diaeresis) 

oe 

247 

oe 

lowercase oe ligature 

0 

248 

0 

lowercase o with slash 

u 

249 

u 

lowercase u with grave accent 

u 

250 

u 

lowercase u with acute accent 

u 

251 

0 

lowercase u with circumflex 

u 

252 

u 

lowercase u with umlaut, (diaeresis) 

y 

253 

y 

lowercase y with umlaut, (diaeresis) 

? 

254 

— 

[reserved] 

? 

255 

— 

[reserved] 
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VAXTPU File Support 


When you edit with VAXTPU, some file attributes may be changed. 
VAXTPU supports some file attributes in that it preserves the particular 
file attribute. VAXTPU does not support other file attributes; it converts 
the file attributes to VAXTPU’s default attribute. For more information 
on file attributes, see the VMS Record Management Services Manual. 
Table F-1 shows the file attributes that VAXTPU supports. It also lists 
the default file attributes for VAXTPU. 


Table F-1 VAXTPU Support of File Attributes 


File Organization 

Status as Supported or Unsupported 

Index 

Unsupported 

Relative 

Unsupported 

Sequential 

Record Format 

Supported (default) 

Fixed length 

Unsupported 

Stream 

Supported 

Stream-CR 

Supported 

Stream-LF 

Supported 

Undefined 

Supported 

Variable length 

Supported (default) 

VFC 

Record Attribute 

Unsupported 

Block 

Supported 

Carriage return 

Supported (default) 

FORTRAN 

Unsupported 

None 

Supported 

Print 

Unsupported 
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EVE$BUILD Module 


VAXTPU includes a module, EVE$BUILD, for building applications on 
EVE. 

EVE$BUILD is a tool for modifying EVE or layering other products on 
EVE. EVE$BUILD compiles VAXTPU code with an existing EVE section 
file to produce a new section file. This new file can define either a new 
version of EVE or a new product. Both customers and Digital developers 
can use EVE$BUILD. 

In using these instructions, type uppercase strings exactly as they appear 
here. Replace lowercase strings wdth appropriate values. For example, 
in the expression product_MASTER.FILE, the string “product” indicates 
that you should substitute the product n£une of your choice. The string 
“MASTER.FILE” must be appended to the product name exactly as it 
appears in these comments. 

These instructions cover the following: 

• How to prepare code for use with EVE$BUILD 

• How to invoke EVE$BUILD 

• What happens when you use EVE$BUILD 


How to Prepare Code for Use with EVE$BUiLD 

For purposes of this section, it is assumed you have VAXTPU code that 
modifies EVE or layers another product on EVE. To turn this code into a 
section file using EVE$BUILD, follow the guidelines in this section. 

There are seven areas in which you must observe special coding 
conventions: 

• Module identifiers 

• Parsers 

• Initialization 

• Command synonyms 

• Status line fields 

• Exit handlers 

• Quit handlers 
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EVE$BUILD Module 

G.1 How to Prepare Code for Use with EVE$BUILD 


G.1.1 Module Identifiers 

Org8inize the VAXTPU code into one or more modules. (This section 
defines “module” in more detail below.) Once you set up one or more 
modules, EVE$BUILD provides an audit trail showing what version of 
each module was used to build each new section file. Digital recommends 
that you put into one or more modules all the code to be used with 
EVE$BUILD. 

To define a module, create a file containing one or more VAXTPU 
procedures and (if appropriate) one or more executable statements. All 
procedures and statements in a module should be related to the same 
task or subject. Then insert a new procedure at the beginning of the 
module. This procedure will return an “ident,” or module identifier, which 
EVE$BUILD tracks during the build process. Use the following format for 
this procedure: 

PROCEDURE facility_MODULE_IDENT 
RETURN "version-number”; 

ENDPROCEDURE; 

In place of “facility,” use a unique module identifier of up to 15 characters. 
If the VAXTPU code in the module is part of a Digital product, begin the 
identifier with the registered product facility code such as EVE or NOTES, 
followed by a dollar sign and the specific module name. For example, the 
facility used in the major EVE module is EVE$CORE. As a result, the 
module containing EVE$CORE has the identifier EVE$CORE_MODULE_ 
IDENT. 

If the code is not part of a Digital product, do not use a dollar sign in the 
module identifier. 

In place of “version-number,” use any string of up to 15 characters 
identifying the version number of the module. 

EVE$BUILD keeps a list showing the ident of each module it uses in a 
build. The list is kept in a file referred to as the .LIST file. This file is 
discussed in Section G.2. In EVE, the format used for the version number 
string is Vnn-mmm, The characters “nn” represent the major version 
number of EVE to which the module belongs. The characters “mmm” 
represent the edit number. 

The following code is the _MODULE JDENT procedure used by the 
module EVE$CORE.TPU: 

PROCEDURE eve$core_module_ident 
RETURN "V02-242"; 

ENDPROCEDURE; 


G-2 







EVE$BUILD Module 
G.1 How to Prepare Code for Use with EVE$BUILD 


G.1.2 Parsers 

EVE$BUILD can accommodate one or more user-written parsing routines 
in addition to the parser included in EVE. If you choose to include a parser 
in your product, the parser can either supplement or replace EVE’s parser. 

If you include one or more parsers in your product, the module containing 
the parser should define a variable of the following form: 

EVE$X_ENABLE_PARSER_facility 

Replace the term “facility” with the name of the module in which the 
parsing routine appears. For example, if the parser occurs in the module 
SCHEDULER, the variable is as follows: 

EVE$X_ENABLE_PARSER_SCHEDULER 

Next, name the procedure implementing the parser. If the product is not a 
Digital product, use the following format: 

facility_PROCESS_COMMAND 

Replace the term “facilit}^ with the name of the module in which the 
par sing routine appears. For example, if the parser occurs in the module 
with the ident SCHEDULER_MODULE_IDENT, the procedure has the 
following name: 

SCHEDULER_PROCESS_COMMAND 

If the product is a Digital product, name the procedure using the following 
format: 

facility$PROCESS_COMMAND 

EVE has a procedure named EVE$PARSER_DISPATCH that defaults to 
the following code: 

PROCEDURE EVE$PARSER_DISPATCH (the_coinmand) 
EVE$PROCESS_COMMAND (the_command); 

ENDPROCEDURE; 

If you do not define a parser-related variable, then the default 
EVE$PARSER_DISPATCH is put into the .INIT file. 

If you do define one or more parser-related variables, EVE$BUILD verifies 
that a corresponding /ac//ity_PROCESS_COMMAND procedure exists 
for each variable. If not, the build fails. If the corresponding procedure 
does exist, EVE$BUILD then adds the following code to EVE$PARSER_ 
DISPATCH just before the call to EVE$PROCESS_COMMAND: 

IF EVE$X_ENABLE_PARSER_facility 
THEN 

IF (facility_PROCESS_COMMAND (THE_COMMAND)) 

THEN 

RETURN; 

ENDIF; 

ENDIF; 
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G.1 How to Prepare Code for Use with EVE$BUILD 


If you want a particular module’s parser to supersede EVE’s parser, your 
parser should return a true status whether or not it can parse a command. 
If you want your parser to supplement EVE’s parser, your parser should 
return a false status if it c 2 innot parse a command. 'The false status allows 
the parsers in other modules, and finally EVE’s parser, to try to parse the 
command. 'The parsers are called in the order in which they appear in the 
master file. (The master file is discussed in Section G.2.) 


G.1.3 Initialization 

EVE$BUILD allows module-specific initialization. 'Ib perform 
initialization in a module, put an initializing procedure in the module 
and name the procedure using the following format: 

facility_MODULE_INIT 

Replace the term “faciUt}^” with the name of the module in which the 
procedure appears. For example, if it occurs in the module SCHEDULER_ 
MODULEJDENT, the procedure is named as follows: 

SCHEDULER_MODULE_INIT 

The EVE module EVE$CORE.TPU contains a null procedure called 
EVE$INIT_MODULES. EVE$BUILD replaces EVE$INIT_MODULES 
with a procedure that calls each procedure whose name ends with 
_MODULE_INIT. The initialization procedures are called in the order in 
which they are found in the master file. (The master file is discussed in 
Section G.2.) 

EVE performs initialization in the following order: 

1 Processing of the procedure TPU$INIT_PROCEDURE 

VAXTPU executes the procedure TPU$INIT_PROCEDURE 
immediately after processing the /DEBUG qualifier. TPU$INIT_ 
PROCEDURE performs the following tasks: 

• Initialization of EVE’s variables and settings 

• Package preinitialization 

• Initialization of EVE’s buffers, windows, and files 

• Initialization of user-written modules 

• Call to the end user’s initialization file, TPU$LOCAL_INIT 

2 Processing of the /COMMAND qualifier if it is present on the DCL 
command line 

3 Processing of the procedure TPU$INIT_POSTPROCEDURE 

VAXTPU executes the procedure TPU$INIT_POSTPROCEDURE after 
processing the /COMMAND qualifier. TPU$INIT_POSTPROCEDURE 
performs the following tasks: 

• Execution of EVE commands in the initialization file 
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G.1 How to Prepare Code for Use with EVE$BUILD 


• Creation and initialization of the $DEFAULTS$ buffer. This buffer 
is a template for all buffers created during an editing session. New 
buffers obtain settings from the $DEFAULTS$ buffer for attributes 
such as margin settings, direction, mode, and so on. 

During the “preinitialization” phase, you can redefine EVE’s variables and 
settings to be compatible with your product. 

Do not redefine any EVE variable or setting unless you are sure you 
understand all the possible side effects on EVE and on your product. Use 
of this option is recommended only for experienced EVE programmers. 

To use preinitialization, put an initializing procedure in a module and 
name the procedure using the following format: 

facility_MODULE_PRE_INIT 

Replace the term “facility’ with the name of the module in which the 
initializing procedure appears. For example, if it occurs in the module 
SCHEDULER_MODULE_IDENT, the procedure is named as follows: 

SCHEDULER_MODULE_PRE_INIT 

The EVE module EVE$CORE.TPU contains a null procedure called 
EVE$PRE_INIT_MODULES. EVE$BUILD replaces EVE$PRE_INIT_ 
MODULES with a procedure that calls each procedure whose name ends 
with _MODULE_PRE_INIT. The initialization procedures are called in 
the order in which they are found in the master file. (The master file is 
discussed in Section G.2.) 

Most programmers who are layering a product onto EVE should initiahze 
modules by using procedures of the t 3 T)e /ociZify_MODULE_INIT. Use of 
TPU$LOCAL_INIT should be reserved for the end user. Use of procedures 
of the type ^ctZiZy_MODULE_PRE_INIT should be reserved for very 
experienced EVE programmers. 


G.1.4 Command Synonyms 

A command synonym is a string that produces exactly the same effect as 
an EVE command or phrase. Command synonyms are useful for creating 
foreign-language versions of EVE or a product layered onto EVE. For 
example, you could designate the Swedish string “naasta_bild” to have the 
same effect as the EVE command NEXT SCREEN. 

EVE$BUILD allows you to create synon 3 nns both for EVE commands 
and for user-written commands. This discussion assumes that when 
you create a command synonym, you first choose a root command (the 
EVE command or user-written command for which you want to create a 
synonym), and then equate to the root command a synonym (the string 
that is to produce the same effect as the root command does). 

You can create S 3 uionyms in each module of your product. To create 
synonyms in a module, you perform two steps: 

1 Create an initializing procedure 

2 Place synonym declaration statements in the initializing procedure 
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G.1 How to Prepare Code for Use with EVE$BUILD 


Name the initializing procedure using the following format: 

facility_DECLARE_SYNONYM 

Replace the term “facility” with the name of the module in which the 
procedure appears. For example, if you create the procedure in the module 
SCHEDULER, you would name the procedure as follows: 

SCHEDULER__DECLARE_SYNONYM 

To declare a synonym, use the EVE$BUILD_SYNONYM statement 
in the DECLARE_SYNONYM procedure. This command enters the 
root command and the synonym into EVE’S data structure associating 
synonyms with root commands. Use one EVE$BUILD_SYNONYM 
statement for each synonym you want to declare. The statement has 
the following format: 

EVE$BUILD_SYNONYM ("root_command", "synonym", integer) 

The parameters are as follows: 

root-command — A quoted string naming the command for which 
you want to declare a synonym. The string must not contain spaces. 

If the command contains more than one word, place an underscore 
between the words. 

S 3 monym — A quoted string naming the synonym you want to 
associate with the root command. The string must not contain 
spaces. If the command usually contains more than one word, place an 
underscore between the words. 

integer — Either 0, 1, or 2. 

The value 0 tells EVE$BUILD that the programmer, not EVE$BUILD, 
will create the procedure and parameters implementing the S3nionym. 
This value instructs EVE$BUILD simply to verify that the root 
command exists and to associate the root command with the synonym. 

The value 1 causes EVE$BUILD to perform the following tasks: 

• Verify that the root command exists. 

• Associate the root command with the syiionym. 

• Create a new procedure giving the S 3 mLonym the same effect as the 
root command. 

• Declare how many parameters are expected by the procedure 
implementing the synonym. (That is, if the procedure 
implementing the root command requires two parameters, then 
the procedure implementing the synonym also requires two 
parameters.) 

• Initialize the parameters of the synonym procedure so they equal 
the parameters of the corresponding root procedure. 

The value 2 causes EVE$BUILD simply to associate the root with the 
synonym. Use this value if you are creating a synonym for a phrase 
rather than a command synonym. 
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Example 

The following statement creates a Spanish synonym for the ONE 
WINDOW command and instructs EVE$BUILD to create the necessary 
structures for the s 3 mon 5 Tn: 

EVE$BUILD_SYNONYM ("one_window", "una_ventana", 1) 

You can declare a synonym to be a terminator. A terminator is a command 
that, if bound to a key and executed with a keystroke, tells an EVE 
prompt to stop prompting. For example, when the DO command is bound 
to the DO key, pressing the DO key terminates the prompts resulting from 
several commands, including DEFINE KEY and FIND. 

To make a S 3 monym a terminator, use a EVE$MAKE_SYNONYM_A_ 
TERMINATOR statement in the fociZfry_MODULE_INIT procedure. For 
example, if you wanted to make the string "Haga" a synonym for "DO" and 
to declare "Haga" as a terminator, you would place the following statement 
in the /aciZify_MODULE_INIT procedure for the module: 

EVE$MAKE_SYNONYM_A_TERMINATOR ("DO", "Haga"); 


G.1.5 Status Line Fields 

Using EVE$BUILD, you can create new areas for displaying information 
in the status line that EVE displays under each window. These areas are 
called “fields.” By default, the EVE status line contains fields to display 
the following information: 

• The buffer mapped to the window 

• The text entry mode 

• The direction of the buffer 

A field can display more than one message. For example, the direction 
field in the default EVE status line can display either the string “Forward” 
or the string “Reverse.” 

To add a field to the status line, write a procedure creating the field and 
include the procedure in the appropriate module. The following sample 
procedure creates a field indicating whether a buffer is a read-only buffer: 

! Procedure to put up the "Read-Only" indicator on NO_WRITE buffers 

PROCEDURE eve$nowrite_status__field (the__length, ! Status line indicator 

the_format) 

ON_ERROR 

[OTHERWISE]: 

ENDON_ERROR; 

IF GET_INFO (CURRENT__BUFFER, "no_write") 

THEN 

RETURN FAO (the_format, eve$x_read_only); 

ELSE 

RETURN 

ENDIF; 

ENDPROCEDURE; 
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You will find it helpful to observe the following conventions: 

• Use the following format for the procedure name: 
field_name_STATUS_FIELD 

For example, if you are adding a field to display the current fine 
number and if your facility is called SCHEDULER, the first line of the 
procedure appears as follows: 

PROCEDURE SCHEDULER_LINE_NUMBER_STATUS_FIELD 

• Give the procedure the following input parameters: 

— max_size — The number of unused column spaces in the status 
line before the new field is added to the line. Use this parameter 
to ensure that all messages fit on the status line. 

— the.format — The FAO directive to be used to format the field. 

The module EVE$CORE.TPU contains a procedure called EVE$GET_ 
STATUS_FIELDS that simply returns the null string. EVE$BUILD 
replaces EVE$GET_STATUS_FIELDS vnth the following procedure: 

PROCEDURE EVE$GET_STATUS_FIELDS (the_length, the_fonnat) 

LOCAL remaining, 
the_fields, 
the_field; 

the_fields := 
remaining := the_length; 

RETURN the_fields 

ENDPROCEDURE; 

For each _STATUS_FIELD procedure you put in a module, EVE$BUILD 
inserts the following code just before the “RETURN the_fields” statement: 

the_field := field_name_STATUS__FIELD (remaining, the_format); 

IF LENGTH (the_field) <= remaining 
THEN 

the__fields := the_field + the_fields; 
remaining := remaining - LENGTH (the_field); 

ENDIF; 


G.1.6 Exit and Quit Handiers 

When you create a new or layered product, you can provide one or more 
user-written exit handlers, one or more user-written quit handlers, 
or one or more of both. Depending on how you write the handlers, 
EVE$BUTLD uses your exit or quit handlers either in addition to or 
instead of those provided by EVE. This section contains pointers on 
writing both supplementary and replacement hauidlers. 

When you write an exit handling procedure, name the procedure using the 
following format for a non-Digital product: 

facility_EXIT_HANDLER 
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Use the following format for a non-Digital quit handler: 

facility_QUIT_HANDLER 

Replace the term “facihty” with the name of the module in which the 
handler appears. For example, if the handler occurs in the module with 
the ident SCHEDULER_MODULE JDENT, you name an exit handling 
procedure as follows: 

SCHEDULER__EXIT_HANDLER 

You would name a quit handling procedure as follows: 

SCHEDULER_QUIT_HANDLER 

If the product is a Digital product, name the procedure using the following 
format for an exit handler: 

facility$EXIT_HANDLER 

Use the following format for a quit handler: 

facility$QUIT__HANDLER 

EVE has procedures named EVE$EXIT__DISPATCH and EVE$QU1T_ 
DISPATCH. By default, EVE$EXIT_DISPATCH contains the following 
code: 

PROCEDURE EVE$EXIT_DISPATCH (the_command) 

EVE$EXIT; 

ENDPROCEDURE; 

By default, EVE$QUIT_DISPATCH contains the following code: 

PROCEDURE EVE$QUIT_DISPATCH (the_command) 

EVE$QUIT; 

ENDPROCEDURE; 

If you do not create an exit or quit handling procedure, EVE$BUILD 
puts the default versions of EVE$EXIT_DISPATCH and EVE$QUIT_ 
DISPATCH into the .INIT file. If you create an exit handling procedure, 
EVE$BUILD adds the following code to EVE$EXIT_DISPATCH just before 
the call to EVE$EXIT: 

IF facility__EXIT_HANDLER 
THEN 

RETURN; 

ENDIF; 

If you create a quit handling procedure, EVE$BUILD adds the following 
code to EVE$QUIT_DISPATCH just before the call to EVE$QUIT: 

IF facility_QUIT_HANDLER 
THEN 

RETURN; 

ENDIF; 

If you want a particular module’s exit or quit handler to supersede EVE’s 
handler, your handler should return a true status. If you want your 
handler to supplement EVE’s handler, your handler should return a false 
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status. The false status allows EVE$BUILD to call the handlers in other 
modules and in EVE. 


G.1.7 How to Invoke EVE$BUILD 

To prepare to use EVE$BUILD, define the following foreign command: 

$ BUILD == "EDIT/TPU/NODISPLAY/SECTION=EVE$SECTION- 
_$ /COMMAND=device:[dir]EVE$BUILD/NOINITIALIZATION 

If you specify /SECTION=EVE$SECTION, EVE$BUILD builds your 
product on top of the standard EVE section file. To build your product 
with a different version of EVE, specify a different section file with the 
/SECTION qualifier. 

In most circumstances, you specify either the standard EVE section file 
or your own enhanced EVE section file. No matter which section file you 
specify, you must use the /NODISPLAY qualifier if you use the /SECTION 
qualifier. 

If for some reason you want to rebuild EVE from scratch, you build it 
/NOSECTION and use the EVE$MASTER.FILE that comes with the EVE 
sources. 

After defining the foreign command, create a master file. This file tells 
EVE$BUILD what modules to compile. If your product is not a Digital 
product, neune your master file using the following format: 

facility_MASTER.FILE 

For example, a valid name for a non-Digital product’s master file might be 
as follows: 

SCHEDULER_MASTER.FILE 

If your product is a Digital product, name your master file using the 
following format: 

facility$MASTER.FILE 

Replace “facility” with the name of your product. For example, a valid 
name for a Digital product’s master file might be as follows: 

NOTES$MASTER.FILE 

When you have created and named the master file, type into it the name of 
each file whose contents you want to compile. Usually this means you type 
in the name of each file containing a module that is part of your product. 

If the files containing the modules are not in the same directory as the 
master file, then you must specify the directory name of each module file. 

If one or more of your modules declare synonyms, enter the names of those 
modules at the end of the file. This ensures that all root commands have 
been created before synonyms for root commands are declared. 

EVE$BUILD processes the modules in the order in which they appear in 
the master file. For example, EVE$BUILD calls exit and quit handlers in 
the same order that they occur in the master file. 
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Once you have completed the master file, create a version file in the same 
directory that contains the master file. If your product is not a Digital 
product, name the version file as follows: 

facility_VERSION.DAT 

If your product is a Digital product, name the version file using the 
following format: 

facility$VERSION.DAT 

The version file is a text file containing only the version number for the 
product. This version number is built into the section file as part of the 
value of the procedure EVE$VERSION. 

When you have a foreign command, a master file, and a version file, you 
can invoke EVE$BUILD with the following command: 

$ BUILD facility 

■ For example, if the name of your product was SCHEDULER, you would 
build it by t3T)ing the following: 

$ BUILD SCHEDULER 

You can use the /OUTPUT qualifier to specify the name of the section file 
to create. If you do not use the qualifier, EVE$BUILD prompts for a file 
name. If you respond with a null file name, EVE$BUILD gives the output 
file the same name as the product. 

EVE$BUILD does not produce a log file if /NODISPLAY is used on the 
DCL command line. In addition, EVE$BUILD does not produce a log file 
if /DISPLAY is used on the DCL command line and the build produces 
errors. 


G.2 What Happens When You Use EVE$BUILD 

Each file specified in the master file is read in and compiled. If there are 
any executable statements after the procedure definitions, the statements 
are compiled and executed. Any SAVE or QUIT statements or calls to 
DEBUGON (this procedure is defined in TPU$DEBUG.TPU) are removed 
before execution. 

EVE$BUILD creates the following three output files: 

• The new section file, with a file type of .TPU$SECTION 

• A file preserving the dynamically generated code, with a file type of 
.INIT 

• A file tracking what happened during the build, with a file type of 
.LIST 

All three files have the SEune device, directory, and file name. 

The .INIT file contains the following: 

• EVE$DYNAMIC_MODULE_IDENT 

• EVE$PARSER_DISPATCH 
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• EVE$MODULE_PRE_INIT 

• EVE$MODULEJNIT 

• EVE$GET_HELP_LIBRARY_TOPIC 

• EVE$VERSION 

The .LIST file contains the following: 

• The date and time of the build 

• The version of EVE used 

• The full file specifications of the master file, section file, version file, 
and .INIT file 

• A synopsis on each source module, including the module ident, the 
number of lines in the module, and the full file specification of the file 
containing the module 

• A list of all global variables used in the build 

• A list of all procedures used in the build 
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CURRENT_OFFSET built-in procedure • 7-88 to 
7-89 
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CURRENT_DIRECTION • 7-85 
CURRENT_LINE*7-86 
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ERROR_LINE lexical element *3-26 
ERROR LIN E statement * 7-125 to 7-126 
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ERROR_TEXT lexical element • 3-26 
ERROR_TEXT statement • 7-127 to 7-128 
EVE 

building applications on • G-1 to G-12 
command window • 4-16 
$DEFAULTS$ buffer • 4-32 
initialization files • 4-31 to 4-33 
during a session • 4-32 
effects on buffer settings • 4-32 
Initialization files • 5-10 
input files • 5-20 
message buffer • 4-18 
message window • 4-16 
order of initialization • G-4 
output file • 5-13, 5-20 
restriction on defining GOLD key • 7-472 
sample procedures • B-1 to B-33 
source files • 4-3 
status line • G-7 

use of EDIT/TPU command qualifiers • 5-18 
user window • 4-16 

wildcard characters in file specifications • 5-20 
wildcards in file names • 5-20 
EVE$BUILD-G-1 to G-12 
exit and quit handlers • G-8 
initialization modules • G-4 to G-5 
invoking • G-10 to G-11 
output • G-11 to G-12 
status line field • G-7 to G-8 
synonym creation • G-5 to G-7 
using parsing routines with • G-3 to G-4 
EVE$GET_STATUS_FIELDS procedure • G-8 
EVE$INIT logical name • 4-31 
EVE$PARSER_DISPATCH procedure • G-3 
EVE$SELECTION procedure 

using to obtain EVE’s current selection *4-17 
EVE default settings • 4-32 to 4-33 
EVE source files *1-11 
EXACT keyword 

with LEARN_BEGIN* 7-244 
with SEARCH *7-328 
with SEARCH_QUIETLY* 7-333 
“Examine” string constant parameter to GET_INFO 
7-179 

Examples of DECwindows VAXTPU built-in 
procedures • B-1 to B-33 
Examples of VAXTPU procedures 
ADJUST_HELP*7-23 
ANCHOR • 7-25 
ANY *7-27 
APPEND LINE *7-29 


Examples of VAXTPU procedures (Cont.) 
ARB *7-31 
ASCII *7-33, 7-34 
BEGINNING_OF*7-38 
BREAK*7-39 
CALL_USER*7-42 
CHANGE_CASE*7-46 
COPY_TEXT*7-54 
CREATE BUFFER *7-62 
CREATE_KEY_MAP • 7-64 
CREATE_KEY_MAP_LIST • 7-66 
CREATE_PROCESS • 7-68 
CREATE_RANGE*7-71 
CREATE_WINDOW • 7-79 
CURRENT_BUFFER • 7-80 
CURRENT_CHARCTER•7-82 
CURRENT_COLUMN • 7-84 
CURRENT_DIRECTION • 7-85 
CURRENT_LINE*7-87 
CURRENT_OFFSET • 7-89 
CURRENT_ROW*7-91 
CURRENT_WINDOW • 7-93 
CURRSOR_HORIZONTAL • 7-95 
CURSOR_VERTICAL • 7-98 
DEFINE_KEY*7-103 
DELETE*7-109 
EDIT *7-114 
END_OF*7-116 
ERASE *7-118 

ERASE_CHARACTER * 7-120 
ERROR *7-124 
ERROR_LINE *7-126 
ERROR_TEXT*7-128 
EXECUTE *7-131. 7-132 
EXPAND_NAME*7-137 
FAO*7-139 
FILE_PARSE *7-142 
FILE_SEARCH* 7-145 
GETJNFO*7-160 to 7-161 
HELP_TEXT*7-229 
INDEX *7-231 
INT* 7-233 
KEY_NAME* 7-240 
LENGTH *7-248 
LINE_BEGIN* 7-250 
LINE_END* 7-251 
LOCATE_MOUSE * 7-253 
LOOKUP_KEY* 7-256 to 7-257 
MAP * 7-260 
MARK *7-263 
MATCH *7-265 
MESSAGE *7-269 
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Examples of VAXTPU procedures (Cont.) 
MOVE_HORIZONTAL • 7-279 
MOVE_TEXT* 7-281 
MOVE_VERTICAL • 7-283 
NOTANY* 7-285 
PAGE_BREAK*7-286 
POSITION‘7-290 
QUIT‘7-292 
READ_CHAR‘7-294 
READ_FILE‘7-298 
READ_KEY‘7-302 
REFRESH‘7-311 
REMAIN‘7-312 
RETURN‘7-315 
SAVE‘7-318 
SCAN‘7-320 to 7-321 
SCANL‘7-323 
SCROLL‘7-326 
SEARCH‘7-330 to 7-331 
SEARCH_QUIETLY ‘ 7-335 to 7-336 
SELECT‘7-339 
SELECT_RANGE‘7-341 
SEND‘7-343 

SET (AUTO_REPEAT) ‘ 7-354 
SET (BELL)‘7-356 
SET (DEBUG)‘7-365 
SET (LINE_NUMBER) ‘ 7-417 
SET (SELF_INSERT) ‘ 7-471 
SET (TEXT)‘7-485 
SET (TRACEBACK) ‘ 7-489 
SLEEP ‘ 7-509 
SPANL‘7-514 
SPLIT_LINE‘7-519 
STR‘7-522 
SUBSTR‘7-524 
TRANSLATE‘7-528 
UNANCHOR‘7-531 
UNDEFINE_KEY‘7-533 
UNMAP‘7-537 
UPDATE‘7-539 
WRITE_FILE‘7-545 
EXECUTE built-in procedure‘4-19 
EXIT built-in procedure ‘ 7-133 to 7-134 
EXITIF statement ‘ 3-21 to 3-22 
EXPAND_NAME built-in procedure ‘ 7-135 to 7-137 
Expressions ‘ 3-8 to 3-12 
arithmetic ‘ 3-9 
Boolean ‘3-11 
evaluation by compiler ‘ 3-9 
pattern‘3-11 
relational ‘ 3-10 


Expressions (Cont.) 

types of ‘ 3-9 
Extensible VAX Editor 
See EVE 


F 


FACILITY_NAME keyword ‘ 7-378 
“Facility_name" string constant parameter to GET_ 
INFO‘7-206 

FAO built-in procedure ‘ 7-138 to 7-139 
FAO directives 

with MESSAGE ‘ 7-267 
with MESSAGE_TEXT‘7-270 
Fatal internal error 

resulting from exceeding virtual address space ‘ 
5-1 
File 

default name for journaling ‘ 1-12 
File organization ‘ F-1 

“File_name” string constant parameter to GET_ 
INFO‘7-171. 7-177 

FILE_PARSE built-in procedure‘7-140 to 7-142 
FILE_SEARCH built-in procedure‘7-143 to 7-145 
FILL built-in procedure ‘ 7-146 to 7-148 
“Find_buffer” string constant parameter to GET_ 
INFO‘7-169 

"first” string parameter to ADD_KEY_MAP ‘7-17 
“First” string constant parameter to GETJNFO ‘ 
7-166, 7-167, 7-169, 7-181, 7-183, 7-184, 
7-191,7-218 

“First_marker” string constant parameter to GET_ 
INFO‘7-172 

“First_range" string constant parameter to GET_ 
INFO‘7-172 

FORWARD keyword ‘7-85, 7-379 
with SEARCH ‘ 7-328 
with SEARCH_QUIETLY ‘ 7-333 
Found range selection 
in EVE‘4-18 

Free cursor movement ‘ 7-95, 7-96 
Free marker ‘ 2-9 to 2-10 
Free markers ‘ 7-70 
FREE_CURSOR keyword 
with MARK‘7-261 
Function key 

control code ‘ 7-241 
control sequence ‘ 7-241 
Function procedures ‘ 3-19 


Index-8 






Index 


G 


Gadget • 2-25 

GET_CLIPBOARD built-in procedure *7-149 
example of use • B-11 to B-13 
GET_DEFAULT built-in procedure • 7-151 
GET_GLOBAL_SELECT built-in procedure • 7-153 
example of use • B-13 to B-15 
GETJNFO built-in procedure • 7-156 to 7-161 
buffer variable parameter 

"read_routine"*7-174, 7-201 
COMMAND_LINE keyword parameter 
"line" *7-176, 7-177 
key_name parameter 

"key_modifiers" • 7-162 
marker_variable parameter 
"record_number" • 7-186 
mouse_event_keyword parameter 
"mouse_button" • 7-188 
"window" • 7-188 
SCREEN keyword parameter 
"active_area" • 7-196 
"decwindows" • 7-197 
"event" • 7-199 
"global_select" • 7-199 
"grab_routine" • 7-199 
"icon_name" • 7-199 
"input_focus" • 7-199 
"length" *7-199 
"newjength" • 7-200 
"new_width" • 7-200 
"oidjength"* 7-200 
"old_width" • 7-200 
"originaljength" • 7-200 
"read_routine" • 7-201 
"screenjimits" • 7-201 
"time" • 7-202 
"ungrab_routine" • 7-202 
string constant parameter 
"active_area" • 7-196 
“Ansi_crt”*7-196 
“auto_repeat” • 7-196 
“bell” • 7-205 
“beyond_eob”*7-185 
“beyond.eol”* 7-185, 7-220 
“blink_status” • 7-221 
“blink_video” • 7-221 
“bold_status” • 7-221 
“bold_vldeo” • 7-221 
"bottom" • 7-222 


GET_INFO built-in procedure 
string constant parameter (Cont.) 

“bound” • 7-171, 7-185, 7-221 
“breakpoint” • 7-179 
“buffer” *7-185, 7-193, 7-222 
"callback_parameters” * 7-209 
"callback_routine" * 7-214 
“character” *7-171 
“children” *7-210 
“class” * 7-214 
“client_message” * 7-197 
“client_message_routine” * 7-197 
“column_move_vertical” * 7-206 
“command” *7-176 
“command_file” * 7-176 
“create” *7-177 

“cross_window_bounds” * 7-197 
“current” *7-166, 7-167, 7-169, 7-184, 
7-191, 7-218 

“current_column” * 7-197, 7-222 
“current_row” * 7-197, 7-222 
"decwindows" * 7-197 
“dec_crt2”*7-197 
“dec_crt”*7-197 
“default_directory” * 7-206 
“defined” * 7-190 
“detached_action” * 7-197 
“detached_reason” * 7-198 
“direction” *7-171 
“display” *7-177, 7-206 
“display_value” * 7-186, 7-222 
“edit_mode” * 7-198 
“eightbit”*7-198 
"enable_resize" * 7-206 
“eob_text”*7-171 

“erase_unmodifiable” * 7-169, 7-171 
"event" * 7-199 
“examine” * 7-179 
“facility_name” * 7-206 
“file_name” *7-171, 7-177 
“find_buffer”*7-169 

“first” *7-166, 7-167, 7-169, 7-181, 7-183, 
7-184, 7-191, 7-218 
“first_marker” * 7-172 
“first_range”*7-172 
"global_select" * 7-199 
"grab_routine" * 7-199 
“highjndex” * 7-167 
"icon_name" * 7-199 
“informational” * 7-206 
“Initialization” * 7-177 
“initialization file” * 7-177 
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GETJNFO built-in procedure 
string constant parameter (Cont.) 

“init_file” *7-177 
"inputjocus" • 7-199 
“is__managed” • 7-214 
“is_subclass” • 7-214 
“journaling” *1-12, 5-10, 7-172 
“journaling_frequency” • 7-206 
“journal” *7-177, 7-203 
“journalJile”*1-12, 5-11, 7-172, 7-177, 
7-206 

“journaLname” * 7-172 
"key_mapjist" * 7-222 
“key_mapjist” * 7-172 
"key__modif iers" * 7-162 
“keyjype” * 7-162 

“last” *7-166, 7-167, 7-169, 7-181, 7-183, 
7-184, 7-191, 7-218 
"left" *7-222 

“left_margin” * 7-172, 7-186 
“left_margin_action” * 7-172 
"length" *7-199, 7-223 
"line" *7-176, 7-177 
“line” *7-172 
“line__editing” * 7-199 
“line_number” * 7-179, 7-206 
“local” *7-179 
“map_count” * 7-173 
“maximum jDarameters” * 7-190 
“maxjines” * 7-173 
“menujDOsitlon” * 7-210 
“message_actionJevel” * 7-206 
“message_action_type” * 7-206 
“messageJIags” * 7-207 
“middle_ofJab”* 7-223 
“mlnimumjDarameters” * 7-190 
“mode” *7-173 
“modifiable” *7-173 
“modified” *7-173 
“modify” *7-177 
“mouse” * 7-200 
"mouse_button" * 7-188 
"name" *7-215 

“name” *7-164, 7-173, 7-182 
"newjength" * 7-200 
"new_width" * 7-200 

“next” * 7-166, 7-168, 7-169, 7-180, 7-181, 
7-183, 7-184, 7-191, 7-218, 7-223 
“next_marker” * 7-173 
“next_range” * 7-173 
“nomodify” * 7-177 
“no video” *7-223 


GETJNFO built-in procedure 
string constant parameter (Cont.) 

“no_video__status” * 7-223 
“no_write”*7-174 
“offset” *7-174, 7-186 
“offset_column” * 7-174, 7-186 
"oidjength"* 7-200 
"old_wldth"* 7-200 
“originaLbottom” * 7-223 
"originaljength" * 7-200 
“originaljength” * 7-223 
“originaljop”* 7-223 
“originaLwIdth” * 7-200 
“output” *7-177 
“outputJlle”*7-174, 7-178 
“pad” *7-223 

“pad_overstruckJabs” * 7-207 
“parameter” * 7-180 
“parent” *7-215 
“permanent” * 7-174 
“pld”*7-192 

“post__keyjDrocedure” * 7-204 
“previous” *7-166, 7-168, 7-169, 7-180, 
7-181, 7-183, 7-184, 7-191, 7-218, 
7-223 

“pre_keyjDrocedure” * 7-204 
“procedure” * 7-180 
“promptjength” * 7-200 
“prompt_row” * 7-201 
“read_only” * 7-178 
"read_routine"*7-174, 7-201 
“record_count” * 7-175 
"record_number" * 7-186 
“record_number” * 7-175 
“record_size” * 7-175 
"recover" * 7-207 
“recover” * 7-178 
"resize_action" * 7-207 
“resources” * 7-215 
“reverse_status” * 7-224 
“reverse_vldeo” * 7-224 
"right" * 7-224 

“right_margin”*7-175, 7-186 
“right_margln_action” * 7-175 
“safejorjournaling” * 7-175 
"screenjimits" * 7-201 
“screen^update” * 7-201 
“scroll” *7-201, 7-224 
“scrolLamount” * 7-224 
"scrolLbar" * 7-224 
"scrolLbar_autoJhumb" * 7-224 
“scrolLbottom” * 7-224 
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GET_INFO built-in procedure 

string constant parameter (Cont.) 

“scrolljop”-7-225 
“section” • 7-178 
“section_file”*7-178, 7-207 
“selfjnsert” • 7-204 
“shift_amount” • 7-225 
“shift_key” • 7-204, 7-207 
“special_graphics_status” • 7-225 
“start_character” • 7-178 
“start_record” • 7-178 
“statusjine” • 7-225 
“status_video’’ • 7-225 
“success” • 7-207 
“system”‘7-175 
“tab_stops”*7-175 
"text" *7-215 
“text” • 7-225 
"time" • 7-202 
“timed_message” • 7-207 
"timer" • 7-207 
"top" • 7-225 
“traceback” • 7-207 
“type” *7-165 
“undefined_key” • 7-204 
“underline_status” • 7-225 
“underline_video” • 7-225 
"ungrab_routine" • 7-202 
“unmodifiable_records” • 7-175, 7-186, 
7-193 

“update” *7-208 

“version” • 7-208 

“video” *7-187, 7-193, 7-226 

“visible” *7-226 

“visible_bottom” * 7-226 

“visiblejength” * 7-202, 7-226 

“visible_top” * 7-226 

“vkl00”*7-202 

“vtl 00” *7-202 

“vt200” * 7-202 

“vt300”* 7-202 

"widgetjd" * 7-209 

"widgetjnfo" * 7-216 

"width" * 7-226 

“width” *7-202 

"window" * 7-188 

“within_range” * 7-187 

“write” *7-178 

SYSTEM keyword parameter 
"enable_resize" * 7-206 
"recover" * 7-207 
"resize_action" * 7-207 


GET_INFO built-in procedure 

SYSTEM keyword parameter (Cont.) 

"timer" * 7-207 

WIDGET keyword parameter 

"callbackjDarameters" * 4-11, 7-209 
"widgetjd" * 7-209 
widget variable parameter 
"name" * 7-215 
"text" *7-215 
"widgetjnfo" * 7-216 
widget_variable parameter 
"callback_routine" * 7-214 
window variable parameter 
"left" *7-222 
"length" * 7-223 
"right" *7-224 
"scroll_bar" * 7-224 
"scroll_bar_autoJhumb" * 7-224 
"top" *7-225 
"width" *7-226 
window_variable parameter 
"bottom" * 7-222 

example of use * B-16 to B-19, B-19 to 
B-22 

"key_mapjist" * 7-222 
Global selection 

determining ownership of * 7-199 
fetching grab routine for * 7-199 
fetching information about *7-153 
fetching read request for *7-199 
fetching read routine for*7-174, 7-201 
fetching ungrab routine for * 7-202 
fetching wait time for * 7-202 
obtaining data from * 7-300 
reading information about * 7-299 
requesting ownership of * 7-380 
sending information about to an application * 
7-546 

specifying expiration period for * 7-387 
specifying grab routine for * 7-382 
specifying read routine for * 7-385 
specifying ungrab routine for * 7-389 
support for * 4-6 to 4-8 
Global variable * 3-4 
GOLD key 

restriction on defining in EVE * 7-472 
Grab routine 

fetching event in * 7-199 
global selection 
fetching * 7-199 
specifying * 7-382 
input focus * 7-398 
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Grab routine 

input focus (Cont.) 

fetching* 7-199 
specifying • 7-400 
GRAPHIC_TABS keyword • 7-483 


H 


HEIGHT parameter to SET built-in procedure • 7-391 
HELP_TEXT built-in procedure • 7-228 to 7-229 
“Highjndex” string constant parameter to GET_ 
INFO *7-167 


I 


Icon 

fetching text of • 7-199 

implementing in DECwindows VAXTPU • 7-393, 
7-395 

specifying text for • 7-392 

ICONIFY_PIXMAP parameter to SET built-in • 7-395 
ICON_PIXMAP parameter to SET built-in • 7-393 
Identifier • 3-4 

Ident produced by EVE$BUILD • G-2 
IDENT statement • 3-14 to 3-15 
%IFDEF lexical keyword • 3-36 
%IF lexical keyword • 3-36 
IF statement *3-22 to 3-23 
INDEX built-in procedure • 7-230 to 7-231 
INFORMATIONAL keyword • 7-397 
“Informational” string constant parameter to GET_ 
INFO *7-206 

INFO__WINDOW identifier *7-506 
INFO_WINDOW variable * 4-29 
Initialization files 

default handling * 4-22 
definition * 1-11 
during a session * 4-32 
effects on buffer settings * 4-32 
EVE *4-31 to 4-33 
/INITIALIZATION qualifier * 5-9 to 5-10 
“Initialization” string constant parameter to GET_ 
INFO *7-177 

“Initiallzationjile” string constant parameter to GET__ 
INFO *7-177 
Initializing variables * 2-24 
“Initjlle” string constant parameter to GETJNFO * 
7-177 


Input files *1-9, 5-19 
Input focus 

determining ownership of * 7-199 
fetching grab routine for *7-199 
fetching ungrab routine for * 7-202 
requesting * 7-398 
specifying grab routine for * 7-400 
specifying ungrab routine for * 7-402 
support for * 4-5 to 4-6 
INRANGE case constant * 3-24 
Inserted records * 6-5 
Inserting date *7-138, 7-268, 7-271 
Inserting time *7-138, 7-268, 7-271 
INSERT keyword * 7-404 
Insert mode 

COPY_TEXT*7-53 
MOVE^TEXT* 7-280 
INT built-in procedure * 7-232 to 7-233 
Integer constants * 3-5 
INTEGER data type * 2-5 
/INTERFACE qualifier * 5-10 
Interruption of program * 4-20 
Invisible record * 7-448 
Invoking * 1-9 
Invoking VAXTPU *5-1 
from a batch job * 5-5 
from DCL command procedure * 5-2 
interactively * 5-1 

restriction to consider before * 5-1 
“is__managed” string constant parameter to GET__ 
INFO *7-214 

“is_subclass” string constant parameter to GET_ 
INFO *7-214 


j 


/JOURNAL command qualifier* 1-11, 1-12 
Journal file * 7-307 
default name * 1-12 
getting characteristics of * 7-203 
getting name of * 1-12, 5-11 
recovering buffer contents * 7-307 
security caution * 1-12, 7-59, 7-234, 7-235, 
7-406 
Journaling 

buffer change* 1-11 

converting buffer to journal file name * 7-172 

default file name *1-12 

EVE default behavior * 1-12 

getting file name of buffer change journal * 7-172 
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Journaling (Cont.) 

getting journal file information • 7-203 
keystroke 

enabling and disabling • 7-408 
layered application control *1-12 
recovery of buffer contents • 7-307 
role of source file • 7-308 
sensing a safe buffer *7-175 
sensing the enable of buffer change journaling • 
1-12, 5-10 

sensing the enable of keystroke journaling *1-12, 
5-11 

using both keystroke and buffer change journaling 
• 1-12 

JOURNALING keyword • 7-405 
JOURNALING parameter 

SET built-in procedure • 7-405 
“journaling” string constant parameter 
GETJNFO built-in • 1-12, 5-10 
“Journaling” string constant parameter to GET__ 
INFO *7-172 

“Journallng_frequency” string constant parameter to 
GETJNFO • 7-206 
/JOURNAL qualifier • 5-10 
“journal” string constant parameter 
GETJNFO built-in *7-203 
“Journal” string constant parameter to GETJNFO • 
7-177 

JOURNAL_CLOSE built-in procedure • 7-234 
“JournalJile” GETJNFO request_strlng*7-177 
“journaijile” string constant parameter 
GETJNFO built-in • 1-12, 5-11, 7-172 
“Journaijile” string constant parameter to GET_ 
INFO *7-206 

“journaLname” string constant parameter 
GETJNFO built-in *7-172 
JOURNAL__OPEN built-in procedure * 1-12, 5-11, 
7-235 to 7-237 

controlling errors related to * 7-408 


K 


Key 

See also Key map 
built-in procedures for defining 
DEFINE_KEY* 7-100 
LAST_KEY* 7-242 
LOOKUP_KEY* 7-254 
SET (POST_KEY_PROCEDURE) • 7-442 
SET (PRE_KEY_PROCEDURE) • 7-^44 


buiit-in procedures for defining (Cont.) 

SET (SELF_INSERT) • 7-470 
SET (UNDEFINED_KEY) • 7-490 
UNDEFINE_KEY* 7-532 
creating a name for • 7-238 
Key map 

built-in procedures 

ADD_KEY_MAP*7-17 
CREATE_KEY_MAP • 7-63 
REMOVE_KEY_MAP • 7-313 
SHOW (KEY_MAP) • 7-505 
SHOW (KEY_MAPS) ‘7-505 
Key map list 
See also Key 
built-in procedures 

CREATE_KEY_MAP_LIST • 7-65 
SET {KEY_MAP_LIST) • 7-^10 
SHOW (KEY_MAP_LIST) • 7-505 
SHOW (KEY_MAP_LISTS) • 7-505 
example of fetching • B-19 to B-22 
Key name 
table • 2-6 
Keystroke journaling 

and buffer change journaling • 7-307 
comparative to buffer change journaiing • 1-11 
enabling and disabling • 7-408 
sensing the enable • 1-12, 5-11 
KEYSTROKE_RECOVERY keyword • 7-^08 
KEYSTROKE_RECOVERY parameter 
SET built-in procedure • 7-408 
Keyword *3-12 
ALL 

with EXPAND_NAME‘7-135 
with REMOVE_KEY_MAP‘7-313 
with SET (BELL)‘7-355 
with SET (DEBUG) ‘7-364 
with UPDATE ‘ 7-538 
ANCHOR‘7-24 to 7-25 

with SEARCH ‘ 7-327, 7-328 
with SEARCH_QUIETLY‘7-332 
BELL‘7-355 

with SET (MESSAGE_ACTION_TYPE) ‘ 
7-426 

BLANK_TABS‘7-483 
BLINK 

with SELECT‘7-337 
with SET (PROMPT_AREA) ‘7-446 
with SET (STATUS_LINE) ‘ 7-476 
with SET (VIDEO)‘7-492 
BOLD 

with SELECT‘7-337 
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Keyword 

BOLD (Cont.) 

with SET (PROMPT_AREA) • 7-446 
with SET (STATUS_LINE) • 7-476 
with SET (VIDEO) *7-492 
BROADCAST 

with SET (BELL) *7-355 
BUFFER_BEGIN 

with POSITION *7-287 
with SEARCH *7-327 
with SEARCH_QUIETLY* 7-332 
BUFFER_END 

with POSITION * 7-287 
with SEARCH *7-327 
with SEARCH_QUIETLY * 7-332 
COMMENT 

with LOOK_UP_KEY* 7-254 
CROSS_WINDOW_BOUNDS * 7-361 
DEBUG *7-362, 7-363, 7-364 
DEVICE 

with FILE_PARSE*7-140 
with FILE_SEARCH *7-143 
DIRECTORY 

with FILE_PARSE* 7-140 
with FILE_SEARCH * 7-143 
EOB_TEXT* 7-374 
EXACT 

with LEARN_BEG1N * 7-244 
with SEARCH *7-328 
with SEARCH_QUIETLY* 7-333 
FACILITY_NAME* 7-378 
FORWARD *7-85, 7-379 
with SEARCH * 7-328 
with SEARCH_QUIETLY * 7-333 
GRAPHIC_TABS* 7-483 
INFORMATIONAL * 7-397 
INSERT *7-404 
JOURNALING *7-405 
key name * 2-6 

KEYSTROKE_RECOVERY * 7-408 
KEYWORDS 

with EXPAND_NAME * 7-135 
KEY_MAP 

with LOOK_UP_KEY * 7-254 
KEY_MAP_LIST* 7-410 
LEFT_MARGIN *7-412 
LEFT_MARGIN_ACTION * 7-414 
LINE_BEGIN* 7-249 to 7-250 
with POSITION *7-288 
with SEARCH * 7-327 
with SEARCH QUIETLY *7-332 


Keyword (Cont.) 

LINE_END* 7-251 

with POSITION *7-288 
with SEARCH * 7-327 
with SEARCH_QUIETLY* 7-332 
LINE_NUMBER* 7-416 
MARGINS *7-419 
MAX_LINES* 7-421 
MESSAGE_FLAGS * 7-427 
MODIFIABLE *7-429 
MOUSE 

with POSITION *7-288, 7-289 
NAME 

with FILE_PARSE*7-141 
with FILE_SEARCH * 7-144 
NODE 

with FILE_PARSE* 7-140 
with FILE_SEARCH * 7-143 
NONE 

with SELECT *7-337 
with SET (MESSAGE_ACTION_TYPE) * 
7-426 

with SET (PROMPT_AREA) * 7-446 
with SET (STATUS_LiNE) * 7-476 
with SET (VIDEO) *7-492 
NO_EXACT 

with LEARN_BEGIN * 7-244 
with SEARCH * 7-328 
with SEARCH_QUIETLY * 7-333 
NO_TRANSLATE* 7-483 
NO_WRITE* 7-434 
occluded *3-12 
OFF 

with CREATE_WINDOW*7-77 
with HELP_TEXT* 7-228 
with QUIT *7-291 

with SET (AUTO_REPEAT) * 7-353 
with SET (BELL) *7-355 
with SET (COLUMN_MOVE_VERTICAL) 
7-359 

with SET (CROSS_WlNDOW_BOUNDS) 
7-361 

with SET (DEBUG) * 7-363, 7-364 
with SET (INFORMATIONAL) *7-397 
with SET (LINE_NUMBER) *7-416 
with SET (MODIFIABLE) * 7-429 
with SET (MOUSE) * 7-432 
with SET (NO_WRITE) * 7-434 
with SET (PAD) * 7-437 
with SET (PAD_OVERSTRUCK_TABS) * 
7-439 

with SET (SCREEN_UPDATE) * 7-460 
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Keyword 
OFF (Cont.) 

with SET (SCROLLING) • 7-^67 
with SET (SELFJNSERT) ‘7-470 
with SET (SUCCESS) • 7-479 
with SET (TIMER) • 7-486 
with SET (TRACEBACK) • 7-488 
with SPAWN‘7-515 
ON 

with CREATE WINDOW‘7-77 
with CREATE_WINDOW‘7-77 
with HELP_TEXT‘7-228 
with QUIT‘7-291 

with SET (AUTO_REPEAT) ‘ 7-353 
with SET (BELL) ‘ 7-355 
with SET (COLUMN_MOVE_VERTICAL) ‘ 
7-359 

with SET (CROSS_WINDOW_BOUNDS) ‘ 
7-361 

with SET (DEBUG)‘7-363 
with SET (INFORMATIONAL) ‘7-397 
with SET (LINE_NUMBER) ‘7-416 
with SET (MODIFIABLE) ‘7-429 
with SET (MOUSE)‘7-432 
with SET (NO_WRITE) ‘ 7-434 
with SET (PAD) ‘ 7-437 
with SET (PAD_OVERSTRUCK_TABS) ‘ 
7-439 

with SET (SCREEN_UPDATE) ‘7-460 
with SET (SCROLLING) ‘ 7-467 
with SET (SELFJNSERT) ‘ 7-^70 
with SET (SUCCESS) ‘ 7-479 
with SET (TIMER) ‘ 7-486 
with SET (TRACEBACK) ‘ 7-488 
with SPAWN‘7-515 
OUTPUT_FILE‘7-435 
OVERSTRIKE‘7-436 
PAD ‘ 7-437 

PAD_OVERSTRUCK_TABS ‘ 7-439 
PAGE BREAK‘7-286 
PAGE_BREAK 

with SEARCH ‘ 7-327 
with SEARCH_QUIETLY‘7-332 
PERMANENT‘7-441 
POST_KEY_PROCEDURE ‘ 7-442 
PROCEDURES 

with EXPAND_NAME ‘ 7-135 
PROGRAM ‘ 7-362 

with LOOK_UP_KEY‘7-254 
PROMPT_AREA ‘ 7-446 
REMAIN‘7-312 

with SEARCH‘7-327 


Keyword 

REMAIN (Cont.) 

with SEARCH_QUIETLY ‘ 7-332 
returned by CURRENT_DIRECTION ‘ 7-85 
returned by READ_KEY ‘ 7-301 
REVERSE ‘ 7-85, 7-453 
with SEARCH ‘ 7-328 
with SEARCH_QUIETLY ‘ 7-333 
with SELECT‘7-337 
with SET (MESSAGE_ACTION_TYPE) ‘ 
7-426 

with SET (PROMPT_AREA) ‘ 7-^46 
with SET (STATUS_LINE) ‘7-476 
with SET (VIDEO)‘7-492 
RIGHT_MARGIN‘7-454 
RIGHT_MARGIN_ACTION ‘ 7-456 
SCREEN_UPDATE ‘ 7-460 
SCROLLING‘7-467 
SELFJNSERT‘7-470 
SHIFT_KEY‘7-472 
SPECIAL_GRAPHICS 

with SET (STATUS_LINE) ‘ 7-476 
STATUS_LINE‘7-476 
SUCCESS‘7-479 
SYSTEM‘7-480 
TEXT‘7-483 
TIMER ‘ 7-486 
TRACEBACK‘7-488 
TYPE 

with FILE_PARSE ‘ 7-141 
with FILE_SEARCH ‘7-144 
UNANCHOR ‘ 7-530 to 7-531 
with SEARCH_QUIETLY ‘ 7-333 
UNDEFINED_KEY ‘ 7-490 
UNDERLINE 

with SELECT‘7-337 
with SET (PROMPT_AREA) ‘ 7-446 
with SET (STATUS_LINE) ‘ 7-476 
with SET (VIDEO) ‘ 7-492 
VARIABLES 

with EXPAND_NAME‘7-135 
VERSION 

with FILE_PARSE‘7-141 
with FILE_SEARCH ‘ 7-144 
VIDEO ‘ 7-492 
with SET‘7-347 to 7-348 
with SHOW ‘ 7-505 to 7-506 
Keyword constants ‘ 3-5 
KEYWORD data type ‘ 2-5 to 2-7 
Keywords 
iexicai ‘ 3-36 


Index-15 





Index 


KEYWORDS keyword 

with EXPAN D_NAME • 7-135 
KEY_MAP keyword 

with LOOK_UP_KEY* 7-254 
KEY_MAP_LIST keyword *7-410 
“Key_map_list” string constant parameter to GET_ 
INFO *7-172 

KEY_NAME built-in procedure • 7-238 to 7-241 
“Key_type” string constant parameter to GETJNFO • 
7-162 

K1LL_SELECTI0N client message • 7-344 


L 


"last" string parameter to ADD_KEY_MAP • 7-17 
“Last” string constant parameter to GETJNFO • 
7-166, 7-167, 7-169, 7-181, 7-183, 7-184, 
7-191, 7-218 

LAST_KEY built-in procedure • 7-242 
LEARN data type • 2-7 to 2-8 
LEARN_ABORT built-in procedure • 7-243 
LEARN_BEGIN built-in procedure • 7-244 to 7-246 
LEARN_END built-in procedure • 7-244 to 7-246 
Left margin 

setting records • 7-448 
LEFT_MARGIN keyword • 7-412 
“Left_margin” string constant parameter to GET_ 
INFO *7-172, 7-186 

LEFT_MARGIN_ACTION keyword *7-414 
“Left_margin_action” string constant parameter to 
GETJNFO *7-172 

LENGTH built-in procedure * 7-247 to 7-248 
Lexical element * 3-1 
Lexical keywords * 3-36 to 3-38 
Line break 

in data from global selection * 7-300 
LINE command * 4-18 
Line mode editing * C-3 
Line-mode editor 
example * A-1 

“Line” string constant paramefer to GETJNFO • 
7-172 

Line terminator 
deleting * 7-28 

LINE_BEGIN keyword * 7-69, 7-249 to 7-250, 
7-273 

with POSITION *7-288 

with SEARCH * 7-327 

with SEARCH QUIETLY *7-332 


“Line_editing” string constant parameter to GET_ 
INFO *7-199 

LINE_END keyword *7-69, 7-251, 7-273 
with POSITION * 7-288 
with SEARCH *7-327 
with SEARCH_QUIETLY * 7-332 
LINE_NUMBER keyword * 7-416 
“Line_number” string constant parameter to GET_ 
INFO *7-179, 7-206 
List 

specifying as a resource value *4—13 
$LOCAL$INI$ buffer*4-22 
LOCAL declaration * 3-34 to 3-35 
“Local” string constant parameter to GETJNFO * 
7-179 

Local variable * 3-4, 3-20 
Local variables * 3-34 

LOCATE_MOUSE built-in procedure * 7-252 to 
7-253 

Logical names 
EVE$INIT*4-31 
TPU$COMMAND*5-6 
TPU$DEBUG*5-8 
TPU$SECTION*5-16 
Logical operators 
AND operator * 3-7 
NOT operator * 3-7 
OR operator * 3-7 
XOR operator * 3-7 
Longword 

to convert with FAO * 7-138 
to convert with MESSAGE • 7-268 
to convert with MESSAGE_TEXT * 7-271 
LOOKUP_KEY built-in procedure * 7-254 to 7-257 
LOOP statement * 3-21 to 3-22 
“Lowjndex” string constant parameter to GET_ 
INFO *7-167 


M 


Main window widget * 4-16 
MANAGE CHILDREN routine 

See MANAGE_WIDGET built-in procedure 
MANAGE CHILD routine 

See MANAGE_WIDGET built-in procedure 
MANAGE_WIDGET built-in procedure * 7-258 
example of use * B-4 to B-11 
Managing 
of widget 

controlling whether causes mapping * 7-418 
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MAP built-in procedure • 7-259 to 7-260 
MAPPED_WHEN_MANAGED parameter to SET 
built-in procedure • 7-418 
Mapping 
of widget 

controlling whether performed during 
managing *7-418 

“Map_count” string constant parameter to GET_ 
INFO *7-173 
Margin 

default *7-412, 7-419, 7-454 
left 

setting records • 7-448 
setting *7-412, 7-419, 7-454 
margin action 
setting *7-414 
Margin action 
default *7-414 
Margin Action 
default *7-456 
setting * 7-456 
MARGINS keyword * 7-419 
MARK built-in procedure * 7-261 to 7-263 
MARK data type * 2-8 to 2-10 
Marker 

deleting *2-10, 7-108 

determining if record containing is unmodifiable * 
7-186 

fetching display value of record containing * 7-186 
padding effects * 2-10 
video attributes * 2-9, 7-261 
MATCH built-in procedure * 7-264 to 7-265 
“Maximumjjarameters” string constant parameter to 
GETJNFO* 7-190 
MAX_LINES keyword * 7-421 
“Maxjines” string constant parameter to GET_ 

INFO *7-173 
Measurement 

converting units of * 7-50 
Memory 

error resulting from exceeding * 5-1 
Menu bar widget *4-16 
Menu position 
of widget 

fetching in VAXTPU * 7-210 
setting in VAXTPU * 7-422 
MENU_POSITION parameter to SET built-in 
procedure * 7-^22 

“menujjosition” string constant parameter to GET_ 
INFO *7-210 
Message buffer * 4-18 

MESSAGE built-in procedure * 7-266 to 7-269 


Messages * D-1 to D-10 
Message window 
in EVE * 4—16 

MESSAGE_ACTION_LEVEL keyword * 7-424 
“Message_action_level” string constant parameter to 
GETJNFO *7-206 

MESSAGE_ACTION_TYPE keyword * 7-426 
MESSAGE_BUFFER identifier * 7-266 
MESSAGE_BUFFER variable * 4—29 
MESSAGE_FLAGS keyword * 7-427 
“MessageJIags” string constant parameter to GET_ 
INFO *7-207 

MESSAGE_TEXT built-in procedure * 7-270 to 
7-272 

“Middle_ofJab” string constant parameter to GET_ 
INFO *7-223 

Minimal interface example * 4-26 
“Minimum_parameters” string constant parameter to 
GETJNFO *7-190 

“Mode” string constant parameter to GETJNFO* 
7-173 
Modifiability 

setting records * 7-448 
MODIFIABLE keyword * 7-429 
“Modifiable” string constant parameter to GET_ 
INFO *7-173 

“Modified” string constant parameter to GETJNFO* 
7-173 

/MODIFY qualifier *5-12 

“Modify” string constant parameter to GET_INFO * 
7-177 

MODIFY_RANGE built-in procedure * 7-273 to 
7-277 

Module declaration 
syntax *3-15 

MODULE statement * 3-14 to 3-15 
Modules used with EVE$BUILD * G-2 
Mouse 

determining support for * 7-432 
determining where drag operation originated * 
7-188 
Mouse button 

fetching information about * 7-188 
MOUSE keyword * 7-432 

with POSITION *7-288, 7-289 
Mouse pad 

implementing * B-4 

“Mouse” string constant parameter to GET_INFO * 
7-200 

MOVE_HORIZONTAL built-in procedure * 7-278 to 
7-279 

MOVE_TEXT built-in procedure * 7-280 to 7-281 
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MOVE_VERTICAL built-in procedure • 7-282 to 
7-283 

Multinational Character Set 

See DEC Multinational Character Set 
Multiple buffers • 7-59 


N 


Name 

widget 

case sensitivity of • 7-74 
NAME keyword 

with FILE_PARSE* 7-141 
with FILE_SEARCH *7-144 
Names for procedures • 3-16 
“Name” string constant parameter to GETJNFO* 
7-164, 7-173, 7-182 

“Next” string constant parameter to GET_INFO* 
7-166, 7-168, 7-169, 7-180, 7-181, 7-183, 
7-184, 7-191, 7-218, 7-223 
“Next_marker” string constant parameter to GET_ 
INFO *7-173 

“Next_range” string constant parameter to GET__ 
INFO *7-173 
NODE keyword 

with FILE_PARSE* 7-140 
with FILE_SEARCH • 7-143 
/NODISPLAY qualifier 

effect on LAST_KEY • 7-242 
to disable screen manager • 6-1 
with EVE$BUILD*G-10 
/NOJOURNAL command qualifier • 1-12 
“Nomodify” string constant parameter to GETJNFO* 
7-177 

NONE keyword 
with MARK *7-261 
with SELECT *7-337 

with SET (MESSAGE_ACTION_TYPE) *7-426 
with SET (PROMPT_AREA) * 7-446 
with SET (STATUS_LINE) * 7-476 
with SET (VIDEO) *7-492 
NOTANY built-in procedure * 7-284 to 7-285 
NOT operator * 3-7 
NONEXACT keyword 

with LEARN_BEGIN* 7-244 
with SEARCH * 7-328 
with SEARCH_QUIETLY* 7-333 
NO_TRANSLATE keyword * 7-483 
“No_video” string constant parameter to GET_INFO • 
7-223 


“No__video_status” string constant parameter to 
GETJNFO *7-223 

“No_write” GETJNFO request_string*7-174 
NO_WRITE keyword * 7-434 
Null parameters * 3-18 
Numeric constant 

specifying radix of * 3-37 


o 


OFF keyword 

with CREATE_WINDOW • 7-77 
with HELP_TEXT* 7-228 
with QUIT *7-291 

with SET (AUTO_REPEAT) • 7-353 

with SET (BELL) *7-355 

with SET (COLUMN_MOVE_VERTlCAL) *7-359 

with SET (CROSS_WINDOW_BOUNDS)* 7-361 

with SET (DEBUG) * 7-363, 7-364 

with SET (INFORMATIONAL) *7-397 

with SET (LINE_NUMBER) *7-416 

with SET (MODIFIABLE) * 7-429 

with SET (MOUSE) *7-432 

with SET (NO_WRITE) *7-434 

with SET (PAD) *7-437 

with SET (PAD_OVERSTRUCK_TABS) *7-439 

with SET (SCREEN_UPDATE) *7-460 

with SET (SCROLLING) * 7-467 

with SET (SELFJNSERT) *7-470 

with SET (SUCCESS) *7-479 

with SET (TIMER) *7-486 

with SET (TRACEBACK) * 7-488 

with SPAWN *7-515 

“Offset” string constant parameter to GETJNFO * 
7-174, 7-186 

“Offset_column” string constant parameter to GET_ 
INFO *7-174, 7-186 

ON keyword 

with CREATE_WINDOW*7-77 
with HELP_TEXT* 7-228 
with QUIT *7-291 

with SET (AUTO_REPEAT) * 7-353 

with SET (BELL) *7-355 

with SET (COLUMN_MOVE_VERTICAL)* 7-359 

with SET (CROSS_WINDOW_BOUNDS) * 7-361 

with SET (DEBUG) *7-363 

with SET (INFORMATIONAL) *7-397 

with SET (LINE_NUMBER) *7-416 

with SET (MODIFIABLE) * 7-429 

with SET (MOUSE) *7-432 
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ON keyword (Cont.) 

with SET (NO_WRITE) • 7-434 
with SET (PAD) • 7-^37 
with SET (PAD_OVERSTRUCK_TABS)« 7-439 
with SET (SCREEN_UPDATE) • 7-460 
with SET (SCROLLING) • 7-467 
with SET (SELF_INSERT) • 7-470 
with SET (SUCCESS) *7-479 
with SET (TIMER) *7-486 
with SET (TRACEBACK) * 7-488 
with SPAWN *7-515 
ON_ERROR statement * 3-25 to 3-31 
location * 3-25 

ON_ERROR Statement * 3-21 
Operators * 3-6 to 3-8 

partial pattern assignment (@) * 2-17 
pattern alternation (|) * 2-16 
pattern concatenation (+) * 2-15 
pattern linking (&) *2-15 
precedence * 3-7 
relationai * 2-18 

“Originai_bottom" string constant parameter to GET_ 
INFO * 7-223 

“Originaljength” string constant parameter to GET_ 
INFO *7-223 

“Original_top” string constant parameter to GET_ 
INFO *7-223 

“Orlginal_width" string constant parameter to GET_ 
INFO * 7-200 
OR operator * 3-7 
Output file *5-12 
OUTPUT parameter 

SET built-in procedure * 7-203 
/OUTPUT qualifier *5-12 

“Output” string constant parameter to GETJNFO * 
7-177 

OUTPUT_FILE keyword * 7-435 
“Output_file” string constant parameter to GET_ 
INFO *7-174, 7-178 
OUTRANGE case constant * 3-24 
OVERSTRIKE keyword * 7-436 
Overstrike mode 
COPY_TEXT*7-53 
MOVE_TEXT* 7-280 
Ownership 

global selection 

determining * 7-199 
losing * 7-202 
requesting * 7-380 
input focus 

determining * 7-199 
losing * 7-202 


Ownership 

input focus (Cont.) 

requesting * 7-398 


P 


Padding effects * 6-11 to 6-12 
version differences * 7-439 
with APPEND_LINE * 7-28 
with ATTACH * 7-35 
with COPY_TEXT*7-53 
with CURRENT_CHARACTER*7-81 
with CURRENT_LINE * 7-86 
with CURRENT_OFFSET*7-88 
with ERASE_CHARACTER * 7-119 
with ERASE_LINE*7-121 
with MARK *7-262 
with MOVE_HORIZONTAL* 7-278 
with MOVE_TEXT* 7-281 
with MOVE_VERTICAL* 7-282 
with READ_FILE * 7-297 
with SELECT *7-338 
with SELECT_RANGE* 7-341 
with SET (PAD) *7-437 
with SPAWN *7-516 
with SPLIT_LINE* 7-518 
PAD keyword * 7-437 

“Pad” string constant parameter to GETJNFO * 
7-223 

PAD_OVERSTRUCK_TABS keyword * 7-439 
“Pad_overstruck_tabs” string constant parameter to 
GETJNFO *7-207 
PAGE_BREAK keyword * 7-286 
with SEARCH *7-327 
with SEARCH_QUIETLY* 7-332 
Parameters 

for procedures * 3-16 to 3-19 
“Parameter” string constant parameter to GET_ 
INFO *7-180 
Parent 
of widget 

fetching in VAXTPU *7-215 
“"parent"” string constant parameter to GET_INFO * 
7-215 

Parentheses 

in expressions * 3-7 
Parser 

maximum stack depth of * 4-2 
Parsers with EVE$BUILD * G-3 to G-4 
Partial pattern assignment (@) *2-17 
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Pattern 

alternation (|)*2-16 
anchoring • 7-24 
built-in procedures *2-13 
compilation •2-18 
concatenation (+) • 2-15 
execution *2-18 
expression • 3-11 
linking (&)*2-15 
operators *2-15 
searching *2-11 
Pattern assignment 
partial (@) *2-17 

PATTERN data type • 2-11 to 2-20 
Pattern matching 
built-in procedures 
ANCHOR *7-24 
ANY *7-26 
ARB *7-30 
LINE_BEGIN* 7-249 
LINE_END* 7-251 
MATCH *7-264 
NOTANY* 7-284 
PAGE^BREAK* 7-286 
REMAIN *7-312 
SCAN *7-319 
SCANL* 7-322 
SPAN • 7-510 
SPANL*7-512 
UNANCHOR *7-530 
PERMANENT keyword * 7-441 
“Permanent” string constant parameter to GET__ 
INFO *7-174 

“Pid” string constant parameter to GETJNFO* 
7-192 
Pixmap 

use of to implent icon in DECwindows VAXTPU * 
7-393, 7-395 
Pointer position * 7-252 

POSITION built-in procedure * 7-287 to 7-290 
example of use * B-25 to B-27 
POST^KEY^PROCEDURE keyword * 7-442 
“Post_keyjDrocedure” string constant parameter to 
GETJNFO *7-204 
Predefined constants 
names *3-13 

“Previous” string constant parameter to GETJNFO* 
7-166, 7-168, 7-169, 7-180, 7-181, 7-183, 
7-184, 7-191, 7-218, 7-223 
PRE_KEY_PROCEDURE keyword * 7-444 
“Pre_keyjDrocedure” string constant parameter to 
GETJNFO *7-204 


Procedural error handler * 3-26 to 3-28 
Procedure 

executing * 4-21 
name * 3-16 

parameter * 3-16 to 3-19 
recommended naming conventions *4-31 
recommended size for * 4-2 
recursive *3-19 

returning result *2-8, 3-19, 7-101 
using LEARN_ABORT In * 7-243 
Procedures 

samples using EVE * B-1 to B-33 
PROCEDURES keyword 
with EXPAND_NAME * 7-135 
PROCEDURE statement *3-15 to 3-21 
“Procedure” string constant parameter to GET_ 
INFO *7-180 
Process 

deleting *7-108 
multiple 

built-in procedures 
ATTACH *7-35 
CREATE^PROCESS * 7-67 
RECOVER_BUFFER * 7-307 
SEND *7-342 
SEND^EOF* 7-346 
SPAWN *7-515 

PROCESS data type * 2-20 to 2-21 
Program 

add to section file * 4-25 

calling VAXTPU from * 4-1, 7-41 

compiling * 4-18 to 4-19 

complex * 4-2 

debugging * 4-33 to 4-37 

deleting *7-108 

executing * 4-19 to 4-21 

interrupting * 4-20 

order * 4-3 

simple * 4-2 

syntax * 4-3 

example * 4-4 
writing *4-1 to 4-14 
PROGRAM data type * 2-21 
Program execution 
built-in procedures 
COMPILE *7-47 
SAVE *7-316 

PROGRAM keyword * 7-362 
with LOOK^UP^KEY* 7-254 
PROMPT_AREA 

video attributes * 7-446 
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PROMPT_AREA keyword • 7-446 
“Promptjength" string constant parameter to GET_ 
INFO *7-200 

“Prompt_row” string constant parameter to GET_ 
INFO • 7-201 


Q 


Qualifier, command 

See EDIT/TPU command qualifiers 
QUIT built-in procedure • 7-291 to 7-292 
Quote characters • 7-112, 7-113 


R 


Radix 

of numeric constant 
specifying • 3-37 

Range 

converting contents of to string format using STR • 
7-520 

deleting • 2-22, 7-70, 7-108 
determining if unmodifiable records are present 
in *7-193 

erasing *2-22, 7-70, 7-117 
moving delimiters of • 7-273 
video attributes • 2-22 
RANGE data type • 2-21 to 2-22 
Read request 
fetching *7-199 
Read routine 

fetching *7-174, 7-201 
specifying • 7-385 

READ^CHAR built-in procedure • 7-293 to 7-294 
READ__CLIPBOARD built-in procedure • 7-295 
READ_FILE built-in procedure • 7-297 to 7-298 
READ_GLOBAL_SELECT built-in procedure • 7-299 
example of use • B-28 to B-30, B-30 to B-31 
READ_KEY built-in procedure • 7-301 to 7-302 
READ_LINE built-in procedure • 7-303 to 7-305 
/READ__ONLY qualifier • 5-13 
“Read__only” string constant parameter to GET_ 
INFO *7-178 

REALIZE__WIDGET built-in procedure • 7-306 
Realizing 

widgets in VAXTPU • 7-306 


Record 

determining if unmodifiable is present *7-175, 
7-186, 7-193 
erasing unmodifiable 

preventing or allowing • 7-375 
fetching display value of *7-186 
sensing unmodifiable erasable state *7-169 
setting attribute • 7-448 
Record attribute • F-1 
Record deleting • 6-5 
Record format • F-1 
Record insertion • 6-5 

RECORD_ATTRIBUTE parameter to SET built-in 
procedure • 7-448 

“Record_count” string constant parameter to GET_ 
INFO *7-175 

“Record__number” string constant parameter to GET_ 
INFO *7-175 

“Record_slze” string constant parameter to GET__ 
INFO *7-175 

/RECOVER command qualifier* 1-11, 7-307 
“Recover” GETJNFO request_string*7-178 
/RECOVER qualifier *5-11, 5-14 
controlling errors related to * 7-408 
Recovery 

of buffer contents *1-11, 7-307 
role of source file * 7-308 
using buffer change journaling * 7-307 
using keystroke journal file 

enabling and disabling * 7-408 
RECOVER_BUFFER built-in procedure * 7-307 to 
7-309 

Recursive procedure * 3-19 
REFRESH built-in procedure *6-10, 7-310 to 7-311 
compared with UPDATE (ALL) *7-538 
Relational expression * 3-10 
Relational operators * 2-18 
REMAIN keyword *7-312 
with SEARCH *7-327 
with SEARCH^QUIETLY* 7-332 
Removal of key map 
built-in procedures 

REMOVE_KEY_MAP * 7-313 
Removal of window * 2-28 
REMOVE__KEY_MAP built-in procedure *7-313 to 
7-314 

Repetitive statements * 3-21 to 3-22 
Reserved word 

built-in procedures * 3-12 
keywords * 3-12 

language elements * 3-13 to 3-14 
predefined constants * 3-13 
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Resizing 

of screen in VAXTPU • 7-391,7-501 
Resource 
of widget 

fetching class and data type of ♦ 7-215 
supported data types for • 4-12 
“resources” string constant parameter to GET_INFO • 
7-215 

Restoring terminal width 
example • A-5 
Restriction 
VAXTPU 

virtual address space • 5-1 
Restrictions 

for subprocess • 2-20 

RETURN statement • 3-26, 3-31 to 3-33, 7-315 
REVERSE keyword • 7-85, 7-453 
with MARK‘7-261 
with SEARCH‘7-328 
with SEARCH_QUIETLY ‘ 7-333 
with SELECT‘7-337 

with SET (MESSAGE_ACTION_TYPE) ‘ 7-426 
with SET (PROMPT_AREA) ‘ 7-446 
with SET {STATUS_LINE) ‘ 7-476 
with SET (VIDEO)‘7-492 

“Reverse_status” string constant parameter to GET_ 
INFO‘7-224 

“Reverse_video” string constant parameter to GET_ 
INFO‘7-224 

RIGHT_MARGIN keyword ‘ 7-454 
“Right_margin” string constant parameter to GET_ 
INFO‘7-175, 7-186 

RIGHT_MARGIN_ACTION keyword ‘ 7-456 
“Right_margin_action” string constant parameter to 
GETJNFO‘7-175 
Running VAXTPU from subprocess 
example ‘ A-5 


s 


“safejorjournaling” string constant parameter 
GETJNFO built-in *7-175 
Sample procedures using DECwindows VAXTPU 
built-in procedures • B-1 to B-33 
Sample VAXTPU procedures 
debugon • 7-365 
delete_alLdefinitlons • 7-533 
inlt_help_key__mapjist • 7-66 
init_sample_key_map • 7-64 
line__number_example • 7-417 


Sample VAXTPU procedures (Cont.) 
malLsub • 7-343 
my_calLuser • 7-43 
remove_comments • 7-312 
SAVE *7-318 
shift__key_handler • 7-257 
show_key_mapsJn Jlst • 7-161 
show_key_mapJlsts • 7-160 
show_selfJnsert • 7-161 
strip_blanks • 7-124, 7-126, 7-128 
strip_elght • 7-528 
toggle_selfJnsert • 7-471 
traceback_example • 7-489 
user__change_mode • 7-103 
user__change_windows • 7-290 
user_clear__key • 7-533 
user_collect_rnos • 7-145 
user_dcl jDrocess • 7-68 
user_define_edtkey • 7-240 
user_define_key • 7-103 
user_delete • 7-89 
user_delete_char • 7-29 
user_delete__extra • 7-109 
user_delete_key • 7-120 
user_display__current__character • 7-82 
user__display_help • 7-23 
user_display_key_mapjist • 7-160 
user__displayjDOsitlon • 7-522 
user_do*7-131 
user__double_parens • 7-265 
user_edit__strlng *7-114 
user_emphasi 2 e__message • 7-509 
user__end_ofJine • 7-251 
user_erase_message__buffer • 7-315 
user_eraseJo__eob • 7-71 
user__error__messsage • 7-139 
userJao_converslon • 7-139 
userjind_chap • 7-330, 7-335 
userjind_mark_twain • 7-514 
userJindjDarens • 7-320 
userJindjDrocedure • 7-27 
userjind_string • 7-315 
userJree-cursor_up • 7-98 
userJree_cursor_down • 7-98 
userJree_cursorJeft • 7-95 
userJree__cursor_right • 7-95 
user_getjnfo*7-160 
user__get_keyJnfo • 7-256 
user__go_down • 7-91 
user__go_up • 7-91 
user__help • 7-229 
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Sample VAXTPU procedures (Cont.) 
user_help_buffer • 7-62 
user_help_on_key • 7-302 
user_include_file • 7-38 
user_initial_cap • 7-524 
userjs_character • 7-231 
userjowercasejine • 7-46 
user_make_window • 7-79 
user_mark ♦ 7-248 
user_message_window • 7-260 
user_move_8_lines • 7-283 
user_move_byJines • 7-279 
user_move_text • 7-281 
user_move_to_mouse • 7-253 
user_next_page • 7-286 
user_next_screen • 7-93 
user_not_quite_working • 7-39 
user_one_window_to_two • 7-537 
user_on_eol • 7-269 
userjsaste • 7-116, 7-263 
user_print • 7-485 

user_prompt_number • 7-233, 7-305 
user_quick_parse • 7-137 
user_quit • 7-292 
user_quote • 7-294 
user_remove_blank_lines • 7-514 
user_remove_comments • 7-25 
user_remove_crlfs • 7-118 
user_remove_dsrlines • 7-250 
user_remove_non_numbers • 7-323 
user_remove_numbers • 7-514 
user_remove_odd_characters • 7-321 
user_remove_paren_text • 7-531 
user_repaint • 7-311 
user_replace_prefix • 7-31 
user_ring_bell • 7-356 
user_runoffJine • 7-87 
user_scroll_buffer • 7-326 
user_search_for_nonalpha • 7-285 
user_search_range • 7-331, 7-336 
user_select • 7-341 
user_show_direction • 7-85 
user_show_firstJine • 7-539 
user_simplejnsert • 7-54 
user_slow_down_arrow • 7-354 
user_slow_up_arrow • 7-354 
user_splitjine • 7-84, 7-519 
user_startJournal • 7-142 
user_start_select • 7-339 
userjab • 7-33 
user_test_key • 7-34 


Sample VAXTPU procedures (Cont.) 
user_toggle_directlon • 7-80 
user_top • 7-38 
user_tpu • 7-132 
user_trans_text • 7-528 
user_two_window • 7-298 
user_upcase_ltem • 7-46 
user_what_is_comment • 7-256 
user_write_file • 7-545 
SAVE built-in procedure • 7-316 to 7-318 
SCAN built-in procedure *7-319 to 7-321 
SCANL built-in procedure • 7-322 to 7-323 
Screen 

enabling resizing of *7-372 
resizing * 7-391, 7-501 
specifying size of * 7-458 
updating 

controlling support for * 7-460 
SCREEN keyword 

using with widget-related built-in procedures *4-16 
Screen layout 

built-in procedures 

ADJUST_WINDOW * 7-19 
CREATE_WINDOW * 7-77 
MAP * 7-259 
REFRESH*7-310 
SHIFT *7-503 
UNMAP *7-536 
UPDATE*7-538 

Screen manager * 2-28, 6-1 to 6-12 
automatic update * 6-7 
line changes * 6-6 
partial update * 6-8 
specific window update * 6-8 
suppressing updates * 6-6 
update all windows * 6-9 
update order * 6-7 
updates * 6-6 

update with ADJUST_WINDOW*7-22 
update with CURSOR_HORIZONTAL*7-94 
update with CURSOR_VERTICAL*7-97 
Screen object 

in VAXTPU *4-14 
Screen update 

See Screen manager 
SCREEN_UPDATE keyword * 7-460 
“Screen_update” string constant parameter to GET_ 
INFO *7-201 
Scroll bar 

disabling * 7-462 
enabling * 7-462 
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Scroll bar slider 

adjusting automatically • 7-224 
Scroll bar widget 

example of fetching • B-19 to B-22 
SCROLL built-in procedure *6-10, 7-324 to 7-326 
Scrolling 

effect of on cursor position • 7-324 
effect of on editing point • 7-324 
with records deleted • 6-5 
with records inserted • 6-5 
SCROLLING keyword • 7-467 
“Scroll” string constant parameter to GET_INFO • 
7-201, 7-224 

“Scroll_amount” string constant parameter to GET_ 
INFO • 7-224 

“Scroll_bottom” string constant parameter to GET_ 
INFO *7-224 

“Scroll_top” string constant parameter to GET_ 
INFO *7-225 
Search 

anchored * 7-24 
anchoring a pattern * 2-19 
1|or pattern *2-11 

ijinanchorlng pattern elements * 2-19 to 2-20 
SEARCH built-in procedure * 7-327 to 7-331 
SEARCH_QUIETLY built-in procedure * 7-332 to 
7-336 


Section files *5-16 

created with EVE$BUILD * G-10 to G-11 
creating * 4-23 
debugging * 4-34 

i efault*4-21 
efinition * 1-10 
xtending * 4-24 
processing * 4-24, 4-25 
Recommended conventions * 4-28 
/SECTION qualifier *4-25, 5-16 
“Seiction" string constant parameter to GETJNFO < 
7-178 

“Seictionjile” string constant parameter to GET_ 
INFO *7-178, 7-207 


Security considerations * 1-12, 7-59, 7-234, 7-235, 
' 7-406 

Se|.ECT built-in procedure * 7-337 to 7-339 
Selection *4-16 
dynamic *4-17 
found range * 4-18 
Ctatic*4-17 

Using MODIFY_RANGE built-in to alter *7-273 
Select range 
In EVE *4-16 


SELECT_RANGE built-in procedure * 7-340 to 
7-341 

SELFJNSERT keyword * 7-470 
“Selfjnsert” string constant parameter to GET_ 
INFO *7-204 
Semicolon 

as statement separator* 1-8, 3-4, 3-15, 3-16, 

3- 17,4-3 

SEND built-in procedure * 7-342 to 7-343 
SEND_CLIENT_MESSAGE built-in procedure * 
7-344 to 7-345 

SEND_EOF built-in procedure * 7-346 
Separator 

semicolon used as* 1-8, 3-4, 3-15, 3-16, 3-17, 

4— 3 

SET (ACTIVE_AREA) built-in procedure * 7-350 
SET (AUTO_REPEAT) built-in procedure * 7-353 to 
7-354 

SET (BELL) built-in procedure * 7-355 to 7-356 
SET (CLIENT_MESSAGE) built-in procedure * 7-357 
to 7-358 

SET (COLUMN_MOVE_VERTICAL) built-in 
procedure * 7-359 to 7-360 
SET (CROSS_WINDOW_BOUNDS) built-in 
procedure * 7-361 

SET (DEBUG) built-in procedure * 7-362 to 7-365 
SET (DEFAULT_DIRECTORY) built-in procedure * 
7-366 

SET (DETACHED_ACTION) built-in procedure * 
7-367 to 7-369 

SET (DISPLAY_VALUE) built-in procedure * 7-370 
SET (DRM_HIERARCHY) built-in procedure * 7-371 
SET (ENABLE_RESIZE) built-in procedure * 7-372 
SET (EOB_TEXT) built-in procedure * 7-374 
SET (ERASE_UNMODIFIABLE) built-in procedure * 
7-375 to 7-377 

SET (FACILITY_NAME) built-in procedure * 7-378 
SET (FORWARD) built-in procedure * 7-379 
SET (GLOBAL_SELECT) built-in procedure * 7-380 
SET (GLOBAL_SELECT_GRAB) built-in procedure * 
7-382 

SET (GLOBAL_SELECT_READ) built-in procedure* 
7-385 

SET (GLOBAL_SELECT_TIME) built-in procedure * 
7-387 

SET (GLOBAL_SELECT_UNGRAB) built-in 
procedure * 7-389 

SET (HEIGHT) built-in procedure * 7-391 
SET (ICONIFY_PIXMAP) built-in procedure * 7-395 
to 7-396 

SET (ICON_NAME) built-in procedure * 7-392 
SET (ICON_PIXMAP) built-in procedure * 7-393 to 
7-394 
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SET (INFORMATIONAL) built-in procedure • 7-397 
SET (INPUT_FOCUS) built-in procedure • 7-398 
SET (INPUT_FOCUS_GRAB) built-in procedure* 
7-400 

SET (INPUT_FOCUS_UNGRAB) built-in procedure • 
7-402 

SET (INSERT) built-in procedure • 7-404 
SET (JOURNALING) built-in procedure • 7-405 to 
7-407 

SET (KEYSTROKE_RECOVERY) built-in procedure* 
7-408 to 7-409 

SET (KEY_MAP_LIST) built-in procedure * 7-410 to 
7-411 

SET (LEFT_MARGIN) built-in procedure * 7-412 to 
7-413 

SET (LEFT_MARGIN_ACTION) built-in procedure * 
7-414 to 7-415 

SET (LINE_NUMBER) built-in procedure * 7-416 to 
7-417 

SET (MAPPED_WHEN_MANAGED) built-in 
procedure * 7-418 

SET (MARGINS) built-in procedure * 7-419 to 7-420 
SET (MAX_LINES) built-in procedure * 7-421 
SET (MENU_POSITION) built-in procedure * 7-422 
to 7-423 

SET (MESSAGE_ACTION_LEVEL) buiit-in procedure 
*7-424 to 7-425 

SET (MESSAGE_ACTION_TYPE) built-in procedure * 
7-^26 

SET (MESSAGE_FLAGS) built-in procedure * 7-427 
to 7-428 

SET (MODIFIABLE) built-in procedure * 7-429 to 
7-430 

SET (MODIFIED) built-in procedure * 7-431 
SET (MOUSE) built-in procedure * 7-432 to 7-433 
SET (NO_WRITE) built-in procedure * 7-434 
SET (OUTPUT) built-in procedure * 7-203 
SET (OUTPUT_FILE) built-in procedure * 7-435 
SET (OVERSTRIKE) built-in procedure * 7-436 
SET (PAD) built-in procedure * 7-437 to 7-438 
SET (PAD_OVERSTRUCK_TABS) built-in procedure 
*7-439 to 7-440 

SET (PERMANENT) built-in procedure * 7-441 
SET (POST_KEY_PROCEDURE) built-in procedure* 
7-442 to 7-^3 

SET (PRE_KEY_PROCEDURE) built-in procedure * 
7-444 to 7-445 

SET (PROMPT_AREA) built-in procedure * 7-446 to 
7-447 

SET (RECORD_ATTRIBUTE) built-in procedure * 
7-^48 to 7-^50 

SET (RESIZE_ACTION) built-in procedure * 7-451 
SET (REVERSE) built-in procedure * 7-453 


SET (RIGHT_MARGIN) built-in procedure * 7-454 to 
7-455 

SET (RIGHT_MARGIN_ACTION) built-in procedure* 
7-456 to 7-457 

SET (SCREEN_LIMITS) built-in procedure * 7-458 
SET (SCREEN_UPDATE) built-in procedure * 7-460 
to 7-461 

SET (SCROLLING) built-in procedure * 7-467 to 
7-469 

SET (SCROLL_BAR) built-in procedure * 7-462 
example of use * B-22 to B-25 
SET (SCROLL_BAR_AUTO_THUMB) built-in 
procedure * 7-465 
example of use * B-22 to B-25 
SET (SELFJNSERT) built-in procedure * 7-470 to 
7-471 

SET (SHIFT_KEY) built-in procedure * 7-472 to 
7-473 

SET (SPECIAL_ERROR_SYMBOL) built-in 
procedure * 7-474 to 7-475 
SET (STATUS_LINE) built-in procedure * 7-476 to 
7-478 

SET (SUCCESS) built-in procedure * 7-479 
SET (SYSTEM) built-in procedure * 7-480 
SET (TAB_STOPS) built-in procedure * 7-481 to 
7-482 

SET (TEXT) built-in procedure * 7-483 to 7-485 
SET (TIMER) built-in procedure * 7-486 to 7-487 
SET (TRACEBACK) built-in procedure * 7-488 to 
7-489 

SET (UNDEFINED_KEY) built-in procedure * 7-490 
to 7-491 

SET (VIDEO) built-in procedure * 7-492 to 7-493 
SET (WIDGET) built-in procedure * 7-494 

example of use * B-22 to B-25, B-25 to B-27 
using to specify resource values * 4-12 
SET (WIDGET_CALLBACK) built-in procedure * 
7-499 

example of use * B-22 to B-25 
using to specify callback routine * 4-9 
SET (WIDGET_CALL_DATA) built-in procedure * 
7-496 to 7-498 

SET (WIDTH) built-in procedure * 7-501 to 7-502 
SET built-in procedure * 7-347 to 7-349 
WIDGET *4-10 

SHIFT built-in procedure *7-503 to 7-504 
SHIFT key 

restriction on defining in EVE * 7-472 
“Shift_amount” string constant parameter to GET_ 
INFO *7-225 

SHIFT_KEY keyword * 7-472 
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“Shift_key” string constant parameter to GET_INFO • 
7-204, 7-207 

SHOW (KEYWORDS) built-in procedure • 2-5 
SHOW built-in procedure • 7-505 to 7-507 
SHOW DEFAULTS BUFFER command *4-32 
Showing version number • 4-2 
SHOW_BUFFER identifier • 7-506 
SHOW_BUFFER variable • 4-29 
SLEEP built-in procedure • 7-508 to 7-509 
Slider *7-224 

example of fetching • B-19 to B-22 
Source file 

defined • 7-308 
Source files for EVE *1-11 
SPAN built-in procedure *7-510 to 7-511 
SPANL built-in procedure * 7-512 to 7-514 
SPAWN built-in procedure * 7-515 to 7-517 
SPECIAL_GRAPHICS keyword 
with SET (STATUS_LINE) * 7-476 
“Special_graphics_status” string constant parameter 
to GETJNFO* 7-225 

SPLIT_LINE built-in procedure * 7-518 to 7-519 
Startup files * 1-10 to 1-11, 4-21 to 4-33 
command file *1-10 
definition * 1-10 
initialization file* 1-10 
order of execution * 4-22 
section file *1-10 

“Start_character” string constant parameter to GET_ 
INFO *7-178 

/START_POSITION qualifier * 5-17 
“Start_record” string constant parameter to GET_ 
INFO *7-178 
Statement 

separator for * 4-3 
Static selection * 4-17 
Status line 

default information * 7-77 
fields added with EVE$BUILD *G-7 to G-8 
video attributes * 7-476 
STATUS_LINE keyword * 7-476 
“Statusjine" string constant parameter to GET_ 
INFO *7-225 

“Status_video’’ string constant parameter to GET_ 
INFO *7-225 

STR built-in procedure * 7-520 to 7-522 
String 

concatenating * 3-4 

converting contents of buffer to using STR * 7-520 
converting contents of range to using STR * 7-520 
to insert with FAO * 7-138 
to insert with MESSAGE * 7-268 


String (Cont.) 

to insert with MESSAGE_TEXT * 7-271 
String constants * 3-5 
STRING data type * 2-23 to 2-24 
STUFF_SELECTION client message * 7-344 
Subclass 

finding out if a widget is a member of *7-214 
Subprocess 

atDCL ievel*7-67 
built-in procedures 
ATTACH *7-35 
CREATE_PROCESS * 7-67 
RECOVER_BUFFER * 7-307 
SEND * 7-342 
SEND_EOF* 7-346 
built-in procedures for defining 
SPAWN *7-515 
deleting * 7-67 
restrictions * 2-20 
running VAXTPU from * A-5 
within VAXTPU* 7-67 

SUBSTR built-in procedure * 7-523 to 7-525 
SUCCESS keyword * 7-479 
“Success” string constant parameter to GET_INFO * 
7-207 

Supported terminals * 1-8 

Symbols * 3-3 to 3-4 

Synonyms for commands * G-5 to G-7 

Syntax * 4-3 

SYSTEM keyword * 7-480 
“System” string constant parameter to GETJNFO * 
7-175 


T 


TAB_STOPS keyword 
used with SET * 7-481 

“Tab_stops” string constant parameter to GET_ 
INFO *7-175 
Terminal 

behavior * C-1 
DEC_CRT2*C-3 
restoring width * A-5 
setting * C-1 to C-3 

AUTO_REPEAT*C-2 

auxiliary keypad * C-2 

132 columns * C-2 

control sequence introducer * C-2 

CSI*C-2 

cursor * C-2 
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Terminal 

setting (Cent.) 

DEC_CRT*C-2 
edit mode • C-2 
eightbit characters • C-2 
scrolling • C-3 
video attributes • C-3 
wrap • C-4 
support • C-1 
width 

restoring • A-5 
Terminal emulator • 6-4 
Terminal support* 1-8 
TEXT keyword • 7-483 
Text manipulation 
built-in procedures 

APPEND_LINE*7-28 
BEGINNING_OF*7-37 
CHANGE_CASE*7-44 
COPY_TEXT*7-53 
CREATE_BUFFER*7-58 
EDIT *7-111 
END_OF* 7-115 
ERASE *7-117 
ERASE_CHARACTER *7-119 
ERASE_LINE* 7-121 
FILE_PARSE* 7-140 
FILE_SEARCH*7-143 
FILL *7-146 
MOVE_TEXT* 7-280 
READ_FILE* 7-297 
SEARCH * 7-327 
SEARCH_QUIETLY * 7-332 
SELECT *7-337 
SELECT_RANGE * 7-340 
SPLIT_LINE* 7-518 
TRANSLATE *7-526 
WRITE_FILE* 7-543 

“Text” string constant parameter to GET_INFO * 
7-225 

%THEN lexical keyword * 3-36 
Time 

inserting with FAO*7-138 
inserting with MESSAGE * 7-268 
inserting with MESSAGE_TEXT * 7-271 
"Timed_message” string constant parameter to GET_ 
INFO *7-207 
TIMER keyword * 7-486 
Title bar widget * 4-16 
TPU$COMMAND logical name *4-21, 5-6 
TPU$DEBUG logical name * 5-8 
TPU$INIT_PROCEDURE procedure * 4-22, 4-28 


TPU$K_DISJOINT constant * 7-198, 7-368 
TPU$KJNVISIBLE constant *7-198, 7-368 
TPU$K_OFF_LEFT constant * 7-198, 7-368 
TPU$K_OFF_RIGHT constant *7-198, 7-368 
TPU$K_UNMAPPED constant *7-198, 7-368 
TPU$LOCAL_INIT procedure * 4-29 
TPU$LOCAL_INIT_PROCEDURE procedure * 4-23 
TPU$SECTION logical name *4-21, 4-27, 5-16 
TPU$STACKOVER status 
correcting * 4-2 

TPU$WIDGETJNTEGER_CALLBACK callback 
routine *4-9, 4-10 

TPU$WIDGET_STRING_CALLBACK callback routine 
*4-9, 4-10 

TPU$X_MESSAGE_BUFFER variable * 4-29 
TPU$X_SHOW_BUFFER variable * 4-29 
TPU$X_SHOW_WINDOW variable * 4-29 
TPU$_UNKLEXICAL error message * 3-38 
TPU command * 4-19 
TPU debugger * 4-33 to 4-37 
ATTACH command * 4-36 
CANCEL BREAKPOINT command * 4-36 
DEBUGON procedure * 4-35 
DEPOSIT command * 4-36 
DISPLAY SOURCE command *4-36 
EXAMINE command *4-36 
GO command * 4-34, 4-36 
HELP command * 4-36 
invoking * 4-33 
QUIT command *4-36 
SCROLL command * 4-37 
SET BREAKPOINT command * 4-34, 4-37 
SET WINDOW command * 4-37 
SHIFT command *4-37 
SHOW BREAKPOINTS command * 4-37 
SPAWN command * 4-37 
STEP command * 4-35, 4-37 
TPU command * 4-37 
TRACEBACK keyword * 7-488 
“Traceback” string constant parameter to GET_ 

INFO *7-207 

TRANSLATE built-in procedure * 7-526 to 7-529 
“Type” GET_INFO request_string * 7-165 
TYPE keyword 

with FILE_PARSE* 7-141 
with FILE_SEARCH* 7-144 
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UNANCHOR keyword * 7-530 to 7-531 
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UNANCHOR keyword (Cont.) 

with SEARCH_QUIETLY* 7-333 
Unbound code 

use of local variables in • 3-34 
UNDEFINED_KEY keyword • 7-490 
“Undefined_key” string constant parameter to GET_ 
INFO *7-204 

UNDEFINE_KEY built-in procedure • 7-532 to 7-533 
UNDERLINE keyword 
with MARK *7-261 
with SELECT *7-337 
with SET (PROMPT_AREA) *7-446 
with SET {STATUS_LINE) * 7-476 
with SET (VIDEO) *7-492 
“Underline_status” string constant parameter to 
GETJNFO* 7-225 

“Underline_video” string constant parameter to GET_ 
INFO *7-225 
Ungrab routine 
global selection 
fetching * 7-202 
specifying * 7-389 
input focus 

fetching * 7-202 
specifying * 7-402 

UNMANAGE_WIDGET built-in procedure * 7-534 
UNMAP built-in procedure * 7-536 to 7-537 
Unmodifiable record * 7-448 

determining if present *7-175, 7-186, 7-193 
preventing or allowing erasing of * 7-375 
sensing erasable state * 7-169 
“Unmodifiable_records” string constant parameter to 
GETJNFO *7-175, 7-186, 7-193 
UNSPECIFIED data type * 2-24 
Unsupported terminals * 2-29 
UPDATE built-in procedure * 6-9, 7-538 to 7-539 
compared with REFRESH * 7-538 
“Update” string constant parameter to GET_INFO * 
7-208 

Updating windows * 2-29 
User window 
in EVE *4-16 
Utility routines 

forming the VAXTPU callable interface * 4-1, 7-41 


V 


Value(s) 

assigning to widget resources •4-10, 7-494 


Variable 
buffer • 2-4 
global • 3-4 
initializing • 2-24 
local • 3-4, 3-20, 3-34 
VARIABLE declaration • 3-36 
Variables 

recommended naming conventions • 4-31 
VARIABLES keyword 

with EXPAND_NAME • 7-135 
VAXTPU 

built-in procedures • 1-2 
DECwindows • 1-2 
journaling methods *1-11 
relationship with DECwindows features *1-2 
used with UIL* 1-4 
VERSION keyword *7-141 
with FILE_SEARCH« 7-144 
Version number • 4-2 

“Version” string constant parameter to GETJNFO* 
7-208 

Video attribute 

marker * 2-9, 7-261 
PROMPT_AREA* 7-446 
range * 2-22 

SET (VIDEO) built-in procedure * 7-492 
with STATUS^LINE * 7-476 
VIDEO keyword * 7-492 

“Video” string constant parameter to GET_INFO * 
7-187, 7-193, 7-226 
Virtual address space 

VAXTPU restriction concerning * 5-1 
Visibility 

fetching display value of record or window * 7-186, 
7-222 
of record 

using display value to determine * 7-370 
setting record * 7-448 

“Visible” string constant parameter to GETJNFO* 
7-226 

“Visible^bottom” string constant parameter to GET_ 
INFO *7-226 

“VisIbleJength” string constant parameter to GET__ 
INFO *7-202, 7-226 

“VisibleJop” string constant parameter to GET_ 
INFO *7-226 

“VklOO” string constant parameter to GETJNFO* 
7-202 

“VtlOO” string constant parameter to GETJNFO* 
7-202 

“Vt200” string constant parameter to GETJNFO* 
7-202 


Index-28 









Index 


“VtSOO” string constant parameter to GETJNFO* 
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callbackjDarameters • 7-209 
case sensitivity of name • 7-74 
creating • 7-72 
defining a class of • 7-105 
deleting *7-108 

fetching callback routine for *7-214 

fetching children of in VAXTPU *7-210 

fetching class of in VAXTPU * 7-214 

fetching name of *7-215 

finding out if managed in VAXTPU * 7-214 

getting information about *7-216 

listing of * 4-5 

main window * 4-16 

managing * 7-258 

mapped status 

controlling in VAXTPU * 7-418 
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finding out in VAXTPU *7-214 
menu bar 

in VAXTPU *4-16 

menu position of in VAXTPU *7-210 
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fetching in VAXTPU *7-215 
realizing in VAXTPU * 7-306 
resource 

fetching class and data type of In VAXTPU * 
7-215 

scroll bar *7-224, 7-462 
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setting resource values of * 7-494 
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unmanaging * 7-534 

using callback data structure in VAXTPU * 7-496 
widgetjd * 7-209 
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specifying * 4-12 
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example of fetching * B-16 to B-19 
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4-16 
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example of fetching * B-16 to B-19 
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mapping * 2-27, 6-3 
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in EVE *4-16 
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screen updates * 6-7 
scroll bar in * 7-224, 7-462 
scroll bar slider in * 7-224 
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size 
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user 
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example of fetching • B-19 to B-22 
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Word separators • 7-146 
/WRITE qualifier • 5-17 


“Write” string constant parameter to GET_INFO • 
7-178 

WRITE_CLIPBOARD built-in procedure • 7-540 
example of use • B-11 to B-13 
WRITE_FILE built-in procedure • 7-543 to 7-545 
WRITE_GLOBAL_SELECT built-in procedure • 7-546 
example of use * B-31 to B-33 
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How to Order Additional Documentation 


Technical Support 

If you need help deciding which documentation best meets your needs, call 800-343-4040 before placing 
your electronic, telephone, or direct mail order. 


Electronic Orders 

Tb place an order at the Electronic Store, dial 800-DEC-DEMO (800-332-3366) using a 1200- or 2400-baud 
modem. If you need assistance using the Electronic Store, call 800-DIGITAL (800-344-4825). 


Telephone and Direct Mail Orders 


Call 

800-DIGITAL 

809-754-7575 
800-267-6215 

International - 

Internal^ - 


Contact 

Digital Equipment Corporation 

P.O. Box CS2008 

Nashua, New Hampshire 03061 

Local Digital subsidiary 

Digital Equipment of Canada 
Attn: DECdirect Operations KA02/2 
P.O. Box 13000 
100 Herzberg Road 
Kanata, Ontario, Canada K2K 2A6 

Local Digital subsidiary or 
approved distributor 

USASSB Order Processing - WMO/E15 
or 

U.S. Area Software Supply Business 
Digital Equipment Corporation 
Westminster, Massachusetts 01473 


Your Location 

Continental USA, 
Alaska, or Hawaii 

Puerto Rico 
Canada 


^For internal orders, you must submit an Internal Software Order Form (EN-01740-07). 
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Reader’s Comments 


VAX Text Processing Utility 
Manual: Part II 
AA-PBTNA-TE 


Please use this postage-paid form to comment on this manual. If you require a written reply to a software 
problem and are eligible to receive one imder Software Performance Report (SPR) service, submit your 
comments on an SPR form. 


Thank you for your assistance. 


I rate this manual’s: 

Excellent 

Good 

Fair 

Poor 

Accuracy (software works as manual says) 

□ 

□ 

□ 

□ 

Completeness (enough information) 

□ 

□ 

□ 

□ 

Clarity (easy to imderstand) 

□ 

□ 

□ 

□ 

Organization (structure of subject matter) 

□ 

□ 

□ 

□ 

Figures (useful) 

□ 

□ 

□ 

□ 

Examples (useftd) 

□ 

□ 

□ 

□ 

Index (ability to find topic) 

□ 

□ 

□ 

□ 

Page layout (easy to find information) 

□ 

□ 

□ 

□ 


I would like to see more/less 


What I like best about this manual is 


What I like least about this manual is 


I found the following errors in this manual: 
Page Description 


Additional comments or suggestions to improve this manual: 


I am using Version_of the software this manual describes. 


Name/ntle _ 

Company _ 

Mailing Address 


Dept. _ 

_ Date 


Phone 
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